Anthropic-Cybersecurity-Skills/skills/performing-osint-with-spiderfoot/references/api-reference.md

SpiderFoot OSINT API Reference

REST API Endpoints

List Modules

GET /api/modules
Response: [{"name": "sfp_dnsresolve", "descr": "...", "group": "Footprint", "provides": [...]}]

Start Scan

POST /api/startscan
Content-Type: application/x-www-form-urlencoded

scanname=my-scan&scantarget=example.com&usecase=footprint
Response: {"scanid": "abc123"}

Check Scan Status

GET /api/scanstatus/{scan_id}
Response: {"status": "RUNNING"}  # RUNNING, FINISHED, ABORTED, ERROR-FAILED

Get Scan Results

GET /api/scanresults/{scan_id}
Response: [{"type": "INTERNET_NAME", "data": "sub.example.com", "module": "sfp_dnsresolve", "source": "example.com"}]

Delete Scan

GET /api/scandelete/{scan_id}

List Scans

GET /api/scanlist

Scan Use Cases

Use Case	Description
all	All modules (slowest, most comprehensive)
footprint	Attack surface mapping: subdomains, IPs, ports
investigate	Deep analysis: WHOIS, DNS, reputation checks
passive	Passive only: no active probing of target

Data Element Types

Type	Description
INTERNET_NAME	Discovered domain/subdomain
IP_ADDRESS	IP addresses
EMAILADDR	Email addresses
LEAKSITE_CONTENT	Leaked credentials/data
DNS_TEXT	DNS TXT/MX/NS records
LINKED_URL_INTERNAL	URLs on target domain
CO_HOSTED_SITE	Sites sharing same IP
AFFILIATE_INTERNET_NAME	Related domains

CLI Usage (sf.py)

# Start scan via CLI
python sf.py -s example.com -t INTERNET_NAME,IP_ADDRESS -m sfp_dnsresolve,sfp_portscan_tcp

# Passive footprint
python sf.py -s example.com -u passive

# List modules
python sf.py -M

Agent CLI Usage

python agent.py --target example.com --use-case footprint --output report.json
python agent.py --target 203.0.113.5 --use-case investigate --timeout 1200
python agent.py --list-modules --server http://spiderfoot:5001