Pivot Track is a CLI tool and library that helps Threat Intelligence analysts to pivot on IoCs and to track their research results. Right now, Pivot Track is focussed on infrastructure tracking. It uses Nils Kuhnert's "Common OSINT Model" for a common representation of several OSINT source results.
The current feature set of PivotTrack is:
- Query Sources: Use Pivot Track to interact with different OSINT sources (for now Censys and Shodan)
- Store Results: Store the results of your queries, so that you do not have to repeat them all the time
- Track Infrastructure: Run Querys at a pre-defined interval and store results to a predefined output (for now OpenSearch)
- Get Notifications: Get notifications for newly found infrastructure (for now in a file)
Note
Pivot Track is still work in progress and has been implemented during my personal experiments with automation of OSINT research.
Usage: pivottrack [OPTIONS] COMMAND [ARGS]...
Pivot Track helps TI analysts to pivot on IoC and to track their research.
╭─ Options ──────────────────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or │
│ customize the installation. │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────╮
│ init-opensearch This command helps you initializing opensearch indicies, │
│ required for the '--output opensearch' option. │
│ query This module helps to query different sources of OSINT platforms │
│ and databases. │
│ track This command runs pivottrack in non-interactive mode, to execute │
│ queries automatically. │
╰────────────────────────────────────────────────────────────────────────────────────╯
Usage: pivottrack query [OPTIONS] COMMAND [ARGS]...
This module helps to query different sources of OSINT platforms and databases.
╭─ Options ──────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────╮
│ generic This command executes a "generic" search on a given OSINT source. │
│ host This command searches for a host on a given OSINT source. │
╰────────────────────────────────────────────────────────────────────────────────────╯
A "generic" search is a search, that uses the query language of a given OSINT source (i.E. Shodan or Censys).
Usage: pivottrack query host [OPTIONS] SERVICE HOST
This command searches for a host on a given OSINT source.
╭─ Arguments ────────────────────────────────────────────────────────────────────────╮
│ * service TEXT [default: None] [required] │
│ * host TEXT [default: None] [required] │
╰────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────────────╮
│ --raw --no-raw [default: no-raw] │
│ --output TEXT [default: cli] │
│ --config-path TEXT [env var: PIVOTTRACK_CONFIG] [default: None] │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────╯
Usage: pivottrack query generic [OPTIONS] SERVICE SEARCH
This command executes a "generic" search on a given OSINT source.
╭─ Arguments ────────────────────────────────────────────────────────────────────────╮
│ * service TEXT [default: None] [required] │
│ * search TEXT [default: None] [required] │
╰────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────────────╮
│ --raw --no-raw [default: no-raw] │
│ --expand --no-expand [default: expand] │
│ --output TEXT [default: cli] │
│ --config-path TEXT [env var: PIVOTTRACK_CONFIG] [default: None] │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────╯
Usage: pivottrack track [OPTIONS]
This command runs Pivot Track in non-interactive mode, to execute queries
automatically.
╭─ Options ──────────────────────────────────────────────────────────────────────────╮
│ --config-path TEXT [env var: PIVOTTRACK_CONFIG] │
│ [default: None] │
│ --definition-path TEXT [env var: │
│ PIVOTTRACK_TRACK_DEFINITIONS] │
│ [default: None] │
│ --run-once --no-run-once [env var: PIVOTTRACK_TRACK_RUNONCE] │
│ [default: no-run-once] │
│ --interval INTEGER [env var: │
│ PIVOTTRACK_TRACK_INTERVAL] │
│ [default: 600] │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────╯
The definitions, used for automatic tracking, have to follow a certain format. You can find an example here.
Important
This setup guide does not cover the OpenSearch setup.
Providing valid OpenSearch settings is required for using the track command and for the opensearch output of query.
- Create folder for setup:
mkdir pivottrack && cd pivottrack - Clone this repository:
git clone https://github.com/lo-chr/pivot-track.git - Copy example configuration file:
cp pivot-track/example/config.example.yaml config.cli.yaml - Change settings in configuration: Provide required API keys for OSINT services. You can disable connectors with
enabled: False(see Censys connector configuration in example file) - Install CLI application:
pipx install https://github.com/lo-chr/pivot-track(If you get warnings by pipx, you have to solve them) - Set
PIVOTTRACK_CONFIGenvironment variable:export PIVOTTRACK_CONFIG="$(pwd)/config.cli.yaml" - Use Pivot Track, Example:
pivottrack query host shodan 1.1.1.1