sectra 0.2.0

Shodan-style CLI for the SecurityTrails API

sectra

Shodan-style CLI for the SecurityTrails API.

sectra is a lightweight, command-line client for SecurityTrails. It is built for quick lookups and scripting, with JSON output and optional response caching to save quota.

Features

• Shodan-style CLI for common SecurityTrails endpoints
• JSON or pretty output
• Optional on-disk caching for GET requests
• Generic request passthrough for any endpoint

Install

pip install sectra

Authentication

Set your API key in the environment:

export SECURITYTRAILS=YOUR_KEY

Or persist it in a config file:

sectra init --key YOUR_KEY

Usage

sectra --help
sectra ping
sectra usage
sectra domain example.com
sectra subdomains example.com
sectra whois example.com
sectra history-dns example.com A
sectra ip-whois 8.8.8.8

Search

sectra domains-search --query "ns = 'ns1.yahoo.com'"
sectra domains-stats --query "ns = 'ns1.yahoo.com'"
sectra ips-search --query "ip:8.8.8.0/24"
sectra ips-stats --query "ip:8.8.8.0/24"
sectra sql-query --query "select * from domains where apex_domain = 'example.com' limit 5"

Auto pagination

For endpoints that return a scroll_id, you can automatically fetch additional pages.

sectra domains-search --query "ns = 'ns1.yahoo.com'" --pages 3
sectra ips-search --query "ip:8.8.8.0/24" --all
sectra sql-query --query "select * from domains limit 100" --all

Aggregated pagination output

If you prefer a single JSON output for multiple pages, use --aggregate with --pages or --all.

sectra domains-search --query "ns = 'ns1.yahoo.com'" --pages 3 --aggregate
sectra ips-search --query "ip:8.8.8.0/24" --all --aggregate
sectra sql-query --query "select * from domains limit 100" --all --aggregate

SQL API

The SQL API is a separate production endpoint (replacing the old DSLv2 prototype) and is not included in retail packages. You need a SQL API subscription to use it.

sectra sql-query --query "SELECT domain.hostname FROM hosts WHERE domain.apex = 'google.com'"
sectra sql-scroll SCROLL_ID

ASI / V2 APIs

sectra projects
sectra assets-search PROJECT_ID --data '{"query":{"match_all":{}}}'
sectra assets-find PROJECT_ID --params '{"size":10}'
sectra asset PROJECT_ID ASSET_ID
sectra asset-exposures PROJECT_ID ASSET_ID
sectra asset-filters PROJECT_ID
sectra asset-tag-apply PROJECT_ID ASSET_ID critical
sectra asset-tag-remove PROJECT_ID ASSET_ID critical
sectra asset-tags-bulk PROJECT_ID ASSET_ID --data '{"tags":["critical","prod"]}'
sectra project-tags PROJECT_ID
sectra tag-task PROJECT_ID TASK_ID
sectra tags-bulk-assets PROJECT_ID --data '{"tags":["prod"],"asset_ids":["id1","id2"]}'
sectra exposures PROJECT_ID
sectra exposure-assets PROJECT_ID SIGNATURE_ID
sectra static-assets PROJECT_ID
sectra static-assets-bulk PROJECT_ID --data '{"assets":[{"asset_id":"id1","fields":{"note":"owned"}}]}'
sectra company-associated-ips example.com
sectra action-report PROJECT_ID report_type
sectra asi-risks PROJECT_ID
sectra asi-risks-history PROJECT_ID --params '{"page":1}'

Caching

By default, GET responses are cached on disk to reduce repeated API usage.

sectra --cache-ttl 3600 domain example.com
sectra --no-cache domain example.com

Cache location: ~/.cache/sectra (or XDG_CACHE_HOME).

Output formats

sectra --output pretty domain example.com
sectra --output json domain example.com
sectra --output raw domain example.com

Generic request

sectra request GET /domain/example.com
sectra request POST /domains/list --data '{"query":"ns = \'ns1.yahoo.com\'"}'

Configuration

• Config: ~/.config/sectra/config.json (or XDG_CONFIG_HOME)
• Cache: ~/.cache/sectra (or XDG_CACHE_HOME)

Development

pip install -e .
sectra --help

License

MIT