Querying results & reports
... or how to find, filter and reuse everything secator has found.
Every task, workflow and scan you run with secator is saved as a report. You can then list them, inspect them, and query findings across all of them, without running anything again.
This page covers the secator report (secator r) and secator query (secator q) commands.
Where reports are stored
By default, reports are saved under ~/.secator/reports/, grouped by Workspaces and then by runner type:
~/.secator/reports/
└── <workspace>/
├── tasks/
│ ├── 0/
│ │ ├── report.json # runner info + results
│ │ ├── report_url.csv # exporter outputs (one file per output type)
│ │ ├── report_url.txt
│ │ ├── .inputs/ # input files passed to the tools
│ │ └── .outputs/ # raw tool outputs (screenshots, responses...)
│ └── 1/
├── workflows/
│ └── 0/
└── scans/
└── 0/Each run gets the next free number in its folder. A report is referred to by its runner path, <type>/<id>, for example tasks/0, workflows/3 or scans/12. All commands below use this format.
Listing reports
Use secator report list (or secator r list) to list your reports:
The table shows the workspace, runner name, runner path (Id), targets, profiles, start / end dates, elapsed time, status, and vulnerability counts by severity.
Without -w, reports from all workspaces are listed. Use these options to narrow the list:
-w, -ws, --workspace
Only list reports from this workspace.
-r, --runner-type
Only list one runner type: task, workflow or scan.
-d, --time-delta
Only list reports newer than a time delta, e.g. 26m, 1d, 1y.
--status
Filter by runner status, as a case-insensitive regex, e.g. SUCCESS, FAIL, '(RUNNING|FAILURE)'.
-i, --interesting
Only list reports that have vulnerabilities.
--show-children
Also list nested sub-tasks / sub-workflows. By default, only outermost runners are shown.
--show-all
Show all columns, including the report path.
--driver
Query backend to read from: local, mongodb, api or sqlite (see Query backends).
List the scans run in the mydomain workspace in the last two days:
List runs that failed or are still running:
List only reports that found vulnerabilities, with their paths on disk:
Inspecting a report
secator report info <RUNNER_PATH> shows the metadata of one run: name, targets, options, status, timings, context, plus its errors and warnings.
By default, long lists are truncated, the verbose config and output fields are hidden, and only the last error / warning is shown. Use --show-all to see everything:
Showing report results
secator report show prints the results of one or more reports. Pass runner paths as a comma-separated REPORT_QUERY:
Without -w, the current workspace is used (see Workspaces).
Filtering with -q
Use -q / --query to filter results with an expression (see Query syntax):
Formatting with -f
Use -f / --format to print only the fields you need, one line per finding. This works well for piping into other tools.
Use {type.field} placeholders to build a line from several fields:
When the results contain a single output type, you can drop the type prefix:
Use type.field (no braces) to print a single field:
Nested fields work too, e.g. for values stored in extra_data:
Separate one format per output type with ||. Each finding is formatted with the spec that matches its type:
-f also accepts a path to a file containing the format. \n and \t are expanded:
Sorting, counting and grouping
These options reshape the output after the query runs:
-l, --limit
Limit the number of results (0 = no limit).
--sort <field>
Sort by a field, numeric-aware. Prefix the field with - to sort in descending order, e.g. --sort port or --sort -cvss_score.
--uniq
Drop duplicate --format values.
--count
Group identical --format values and prefix each one with its number of occurrences, most frequent first. With --sort, values are ordered by value instead.
--group
Group findings by their output type's default field(s) and list the related values on one row (see below).
Show each vulnerability once, with all the targets it was matched at:
The default --group fields are:
vulnerability
name
matched_at
exploit
name
matched_at
port
host
port
url
host
url
subdomain
domain
host
technology
product
match
tag
category, name
match
--group can be combined with --format, --count and --sort. For example, -q vulnerability --group -f severity --count counts unique vulnerabilities by severity.
Exporting
Use -o / --output to export the results with one or more Exporters, and -of / --output-folder to choose where the files go (the current directory by default):
Deduplication
--dedupe removes duplicate findings, e.g. the same URL found by several tools or runs. --no-dedupe keeps them. When neither is passed, secator uses the runners.remove_duplicates setting:
Time filter
Use -d / --time-delta to keep only recent findings:
Querying with secator query
secator query (or secator q) is the quickest way to search for findings. It accepts the same options as secator r show, but takes the filter expression as its argument:
To scope a query to specific runs, use -rf / --report-filter. It works like the REPORT_QUERY argument of r show:
With no argument, secator q returns all results, filtered by the options you pass:
How the argument is read
secator q <ARG> reads its argument in this order:
Saved query. If
ARGis the name of a saved query, its expression is used (see Saved queries).Filter expression. If
ARGlooks like an expression (it contains an operator such as==,<,~=,&&,||orin [, is a dotted field path likeip.alive, or is an output type name likeurl), it is run as a query.Natural language. Otherwise, the question is sent to the
aitask in chat mode, run against the selected workspace:
Saved queries
Save a query under a name with --save, then run it by name:
Saved queries are stored in the queries section of your config, so you can also manage them with secator config:
Query syntax
-q (for r show) and the argument of secator q use the same expression syntax.
Selecting a type
Use an output type name on its own to select all findings of that type:
See Output types for the list of types. To filter on a field, use type.field:
Operators
==
Equals
port.port == 443
!=
Not equal
url.status_code != 404
>, >=, <, <=
Numeric comparison
vulnerability.cvss_score >= 7
~=
Matches regex (case-insensitive)
url.url ~= 'admin'
!~=
Doesn't match regex (case-insensitive)
subdomain.host !~= '^dev'
in [...]
Value is in list
port.port in [22, 80, 443]
not in [...]
Value is not in list
vulnerability.severity not in [info, low]
type.field
Field is truthy
ip.alive
not type.field
Field is not True
not url.verified
Values can be quoted or not. true / false become booleans, and numbers become numbers. Nested fields use dots, e.g. vulnerability.extra_data.template_id ~= 'cve'.
!=, !~= and not in only match findings that have the field: vulnerability.severity != 'info' doesn't return ports or URLs.
Combining conditions
Combine conditions with && / and (all must match) or || / or (any can match):
MongoDB JSON
You can also pass a MongoDB-style JSON filter:
Unknown fields
If a field doesn't exist on the type you query, secator prints a warning with the list of available fields, so you can use a typo as a quick field reference:
Examples
Query backends
All secator r and secator q commands read from a query backend, selected with --driver:
local
The JSON reports in ~/.secator/reports/ (default).
mongodb
A MongoDB database filled by the mongodb driver.
sqlite
A SQLite database filled by the sqlite driver.
api
A remote API filled by the api driver.
If --driver isn't set, secator uses the first backend listed in drivers.defaults, and falls back to local:
See Drivers to set drivers up.
Deleting reports
secator report delete (or secator r rm) deletes one or more reports. It accepts space- or comma-separated runner paths, and numeric ranges:
The command lists what will be deleted and asks for confirmation. Pass -y / --yes to skip the prompt.
With the local driver, the report folders are removed. With the mongodb, sqlite or api drivers, the runner and its findings are deleted from the backend.
To delete a whole workspace and all its reports, use secator ws rm (see Workspaces).
Last updated