Lookup Urlscan

lookup-urlscan

Submits URLs to URLScan.io for live scanning and retrieves results. For domains, searches existing scans first (uses cached scan if " node tools/clis/urlscan.js domain

Single-shot URL submit (with built-in 30s wait + 5x10s polling) or domain search. Best for fast retrieval inside an investigation chain.

### Full API surface — Python CLI (stdlib only)

```bash
python3 tools/clis/urlscan.py submit  [--visibility V] [--country CC]
                                            [--tags t1,t2] [--user-agent UA]
                                            [--referer R] [--wait]
python3 tools/clis/urlscan.py result 
python3 tools/clis/urlscan.py search "" [--size N]
python3 tools/clis/urlscan.py quota
python3 tools/clis/urlscan.py screenshot  [--out FILE]
python3 tools/clis/urlscan.py dom  [--out FILE]

Stdlib only — no install, no venv.

Capabilities the Node CLI doesn't have:

• Lucene-style search — the killer pivot. Query against URLScan's full database: page.domain, page.url, asn, hash, filename, verdicts.overall.malicious, task.tags, page.country, etc. Combine with AND/OR/NOT.
• Result by UUID — fetch a known scan without re-submitting.
• Quota check — see remaining scan/search/retrieve quota before committing to a batch.
• Screenshot download (screenshot --out img.png) — pull the rendered page screenshot.
• DOM download (dom --out page.html) — pull captured HTML for offline analysis.
• Submission options — country, custom user-agent, custom referer, tags.

Lucene search examples:

# All public scans of a domain in the last 30 days
python3 tools/clis/urlscan.py search "page.domain:malicious.example AND date:>now-30d"

# Phishing kits hosted on Russian ASNs
python3 tools/clis/urlscan.py search "task.tags:phishing AND page.country:RU"

# Pivot by favicon hash (a strong infrastructure fingerprint)
python3 tools/clis/urlscan.py search "hash:5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"

# All scans hitting a specific IP
python3 tools/clis/urlscan.py search "page.ip:185.220.101.45"

Both CLIs accept --dry-run. Both exit code 2 if $URLSCAN_API_KEY is unset (when not in dry-run). Report missing key; do not fabricate.

Visibility — non-negotiable default

Always submit with unlisted visibility unless the user explicitly opts in to public. Public submissions appear on URLScan's global feed and tip off threat actors that you're investigating their infrastructure. Both CLIs default to unlisted. The Python CLI also supports private (Pro tier).

Response format

source: urlscan
indicator: 
query_time: 
verdict: 
final_url: 
ip: 
country: 
domains_contacted: []
ips_contacted: []
screenshot_url: 
scan_url: 
key_findings:
  - 

Rate limits

Free tier: 100 scans/day, 5000 searches/month.

Source reliability (Admiralty default)

Default rating for downstream /score-source: B2 (usually reliable, probably true). Live-scan evidence is strong; verdicts can be noisy — downgrade to C3 if verdict is ambiguous.

Operational notes

• Always use unlisted visibility by default — public submissions expose the indicator and can tip off threat actors.
• Don't submit if the URL is in the user's own infrastructure unless they explicitly request it.

Related skills

• /lookup-virustotal, /lookup-otx — reputation/community context
• /score-source — apply Admiralty rating
• /url-investigation, /domain-investigation

See also

• Integration setup: tools/integrations/urlscan.md
• Node CLI source: tools/clis/urlscan.js
• Python CLI source: tools/clis/urlscan.py
• Official API docs: https://docs.urlscan.io/apis/urlscan-openapi/live-scanning
• Search query syntax: https://urlscan.io/search/

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Liberty91LTD
• Source: Liberty91LTD/cti-skills
• License: MIT
• Homepage: https://liberty91.com/cti-skills

Install and usage instructions live in the source repository linked above.