Skip to content

Usage

Jump to bottom
Eoghan West edited this page Nov 29, 2023 · 11 revisions

list of example commands and an explanation fo what they do.

Start Here

ptdb's functionality is split into the sub commands:

  • query retrieves information from the database.
  • engagement makes new, or modifies old, engagements.
  • info prints info about the current configuration.
  • parse parses command output pased to stdin.
  • pause used to pause command parsing (either local to the current session or globally)
  • resume used to resume command parsing (either local to the current session or globally)
  • config used to change engagement or db configs.
  • server (WIP)
  • client (WIP)

Query Sub-Command

The query sub-command retrieves data from the database and presents it as a table to the user. Most queries fallow the same pattern: $ ptdb query -g <COLUMN-NAMES> -f <TABLE> -- this will sometimes have the addition of -w <CONDITION>. The -g/--get argument tells the program what data to retrieve. The -f/--from argument tells the program what the data is about, in other words, what table (or tables) to query for the data. Lastly -w/--where is a list of conditions, concatinated by OR statements, to filter the returned data with (ex, -w "ip = '127.0.0.1'" "ip LIKE '192.168.1.%'"). If you are familiar with SQL then -g/--get is the SELECT clause, -f/--from is the FROM clause, and the -w/--where is the WHERE clause. putting that together we get: ptdb query -s ip port state version -f hosts -w "port = 80 AND state = 'open'" "port = 443 AND state = 'open'", this command will print a table containing the IPv4 address, port number, state (open/closed/filtered), and service version, of all hosts that have either port 80, or port 443 in the open state. teh output may look something like the following:

$ nmap -sV scanme.nmap.org
...
$ ptdb query -s ip port state version -f hosts -w "ip = '45.33.32.156'"`
 ip           | port  | state    | version
--------------+-------+----------+-----------------------------------------------------------------
 45.33.32.156 | 22    | open     | OpenSSH 6.6.1p1 Ubuntu 2ubuntu2.13 (Ubuntu Linux; protocol 2.0)
 45.33.32.156 | 80    | open     | Apache httpd 2.4.7 ((Ubuntu))
 45.33.32.156 | 135   | filtered |
 45.33.32.156 | 139   | filtered |
 45.33.32.156 | 445   | filtered |
 45.33.32.156 | 593   | filtered |
 45.33.32.156 | 9929  | open     | Nping echo
 45.33.32.156 | 31337 | open     |
(8 rows of data)

The final thing to go over with regards the query sub-command is the -l/--list-columns argument. This argument requires the -f/--from argument. It will print all column names in the target "FROM clause" (-f/--from). For example:

$ ptdb query -l -f hosts
 table_name | column_name
------------+-------------
 dns_names  | record_type
 dns_names  | dns_name
 dns_names  | id
 dns_names  | machine_uid
 dns_names  | command_uid
 dns_names  | cname_for
 dns_names  | txt_value
 machines   | id
 machines   | command_uid
 machines   | ip
 machines   | ipv6
 machines   | mac_adr
 machines   | local_name
 machines   | gateway_to
 ports      | service
 ports      | version
 ports      | tl_protocol
 ports      | command_uid
 ports      | port
 ports      | machine_uid
 ports      | id
 ports      | state
(22 rows of data)

help message (at time of writing):

Used to query the engagement data-bases. if no engagement is specified, the current engagement is used by default.

Usage: ptdb query [OPTIONS]

Options:
  -g, --get <DATA-TO-RETRIEVE>...
          the information to print to the console. (ie. what columns to SELECT from the database). aliases include ['--select', '-s']. [aliases: select] [short aliases: s]
      --engagement [<ENGAGEMENT-NAME>]
          the engagement database to query. (defaults to '~/.config/ptdb/engagement.toml') 
  -q, --query <QUERY>
          manually specify the SQL or GraphQL, query.
  -w, --where <CONDITION>...
          specify an "eq" function call inside a filter derivative. this should be given in a data base specific format.
  -r, --require [<REQUIRED-PREDICATES>...]
          require that listed predicates must be present in return value. (currently has no effect in SQL mode)
  -f, --from <TARGET>
          the target to select from. targets are defined in the config file. aliases include ['--target', '-t']. targets are tables that are joined with other tables using the "JOIN" keyword. (or when using the '--list-columns' flag)
  -l, --list-columns
          lists the columns that can be selected from the target. aliases include ['--get-columns', '--columns', '--list', '--ls']. (targets are designated with the '--from' or '--target').
  -h, --help
          Print help

Engagement Sub-Command

The engagement sub-command handles making new engagements and modifying old ones.

To make a new engagement called "foo" with a server config called "bar" on might run the command: ptdb engagement -n foo -s bar. One can also append the -a/--activate flag to activate this new engagement.

Sometimes one might need to switch engagements -- potentially because you've moved your attention to a new engagement but still need to write a report/writeup for an old engagement, or you just want to reference something from an old engagement. The easiest way to do this is to use the -a/--activate flag, followed by teh name of the engagement to activate: ptdb engagement -a foobar. The more manual way to do this is to delete the engagement symlink and replace it with a new symlink to the desiered engagement file. like this:

$ rm ~/.config/ptdb/engagement.toml
$ ln -s ~/.config/ptdb/engagements/foobar.toml ~/.config/ptdb/engagement.toml

To delete an old engagement it is advised NOT to just delete the toml file as doing so will leave the database data on the SQL/GraphQL server. it is instead adviced to use the -d/--delete argument. That will ensure that both the data from the database AND the toml file get removed.

help message (at time of writing):

get info about an engagement or make new ones. if no engagement is specified, the current engagement is used by default.

Usage: ptdb engagement [OPTIONS]

Options:
  -n, --new <ENGAGEMENT-NAME>
          makes a new engagement and switches to it.
  -e, --engagement [<ENGAGEMENT-NAME>]
          get info on a specific engagement
  -c, --is-complete [<ENGAGEMENT-NAME>]
          returns if the given engagement is completed. if no engagement is provided it will use the current engagement from the config file.
  -d, --delete <ENGAGEMENT-NAME>
          removes an engagement data-base from the sql server.
  -a, --activate [<ENGAGEMENT-NAME>]
          activates an engagement in the config file. aliases include ['--switch-to', '-s']. [aliases: switch-to]
  -s, --server <DB-SERVER-CONF-FILE>
          the sql server config file to use. "default" is assumed if this argument is not provided.
  -h, --help
          Print help

Info Sub-Command

Prints the current status (current engagement, if paused, db host, etc). It takes no arguments.

example output:

$ ptdb info
database name    =>  demo
database host    =>  127.0.0.1
engage complete  =>  false
active status    =>  global: active | local: active

Parse Sub-Command

This sub-command parseses a the output of a command when that output is passed to stdin. It also requires that the exit-status and command get passed as arguemnts using the -e/--exit-status and -c/--command flags respectively. -- Note that parsing manually from teh terminal is only doable with some comamnds. If the command prints important data to stderr then ptdb will not recieve it. In such cases reply on the ptdb shell hooks.

Help text:

$ ptdb parse -h
Runs in stand alone mode. (ie. all commands are parsed and sent to the database from the current process. NOTE: that this is blocking.)

Usage: ptdb parse [OPTIONS]

Options:
  -q, --quiet                      Suppresses all output. (will not suppress fatal errors, like sql errors.)
  -c, --command <EXECUTABLE-NAME>  Sets the command. helpful for when you need to pipe the output of a command directly into ptdb.
  -e, --exit-status <EXIT_STATUS>  the exit status of the command being parsed.
  -h, --help                       Print help

Pause and Resume Sub-Command

Pause and resume do exactly what youd expect they allow you to temporarily stop parsing commands. By default this change will effect only the currnet terminal, but if you add the -g/--global flag then the change will affect other terminal sessions as well.

Help text:

$ ptdb pause -h
Pauses the interpretation of commands until the resume command is issued. By default parsing will be paused for the current terminal session only. Adding "--global" will pause for all terminal session.

Usage: ptdb pause [OPTIONS]

Options:
  -g, --global  pauses parsing globally.
  -h, --help    Print help

Config Sub-Command

Config is only really used to change the activated engagement. It is deprecated and will be removed.

$ ptdb config -h
Used to change configurations.

Usage: ptdb config [OPTIONS]

Options:
  -e, --s-eng <ENGAGEMENT-CONF>  switches to the selected engagement config.
  -s, --s-sql <SQL-SERVptdb config -h
Used to change configurations.

Usage: ptdb config [OPTIONS]

Options:
  -e, --s-eng <ENGAGEMENT-CONF>  switches to the selected engagement config.
  -s, --s-sql <SQL-SERVER-CONF>  switches to the selected SQL server config.
  -h, --help                     Print helpER-CONF>  switches to the selected SQL server config.
  -h, --help                     Print help

Example Commands

  • ptdb query -s ip -f hosts -w "port = 80 AND state = 'open'" "port = 443 AND state = 'open'"" will print all IP adresses that have port 80 OR 443 open. (i.e, are likely to be web server.)
  • ptdb engagement -a -n foobar will create and activate a new engagement called "foobar" with default parameters.
  • ptdb pause to pause locally (or add -g/--global to the command to pause all sessions.)
  • ptdb resume to resume locally (or add -g/--global to the command to resume all sessions.)
  • ptdb info will print basic info about the current state of the program.
Clone this wiki locally