urlscan-cli - Use urlscan from the command line
We are excited to announce the release of urlscan-cli, the official CLI to interact with the urlscan platform . This powerful new tool brings the full capabilities of our platform directly to your terminal, making it easier than ever to integrate URL scanning into your CLI-based workflows.
Key Features
- Comprehensive API support: The CLI supports all our free and pro API endpoints.
- Bulk submissions: Instead of scanning links individually, scan multiple URLs at once.
- Automatic search iteration: Retrieve large datasets by automatically iterating a search.
- Cross-platform support: urlscan-cli is implemented in go and is available for Windows, macOS, and Linux.
To learn more about our API endpoints and how to integrate urlscan in your project, visit our API page.
The majority of commands in urlscan-cli will return raw JSON responses. You
will likely want to parse these with a tool like jq.
Getting Started
Installation is straightforward with multiple options available:
- Pre-built binaries are available for all platforms on GitHub releases.
- macOS users should install via Homebrew:
brew install --cask urlscan/tap/urlscan-cli
Once installed, start by setting up your urlscan API key. You can generate an API key on the User page on urlscan.io.
# Set the API key via keyring
urlscan key set
# Alternatively you can simply supply the API key via the environment
export URLSCAN_API_KEY=xxx
Scanning
Here are some common usage patterns to get you started:
# Submit a single URL for scanning. Returns the scan ID.
urlscan scan submit https://example.com
# Retrieve results for a completed scan
urlscan scan result <uuid>
# Submit and wait on the result
urlscan scan submit https://example.com --wait
# Submit, wait on the result, and download DOM and screenshot
urlscan scan submit https://example.com --download
Bulk scan submission
Scanning multiple URLs in bulk is a common use-case:
# Bulk submit multiple URLs supplied as arguments
urlscan scan bulk-submit http://example.com http://example.net http://example.org
# Wait and return all results
urlscan scan bulk-submit http://example.com http://example.net http://example.org --wait
# Wait and download DOMs and screenshots
urlscan scan bulk-submit http://example.com http://example.net http://example.org --download
Search
# Retrieve the latest 100 scans from urlscan
urlscan search page.domain:example.com --limit 100
# Retrieve unique URLs detected as malicious over the past 5 minutes - aka the "phishing feed"
urlscan search "brand.key:* AND date:>now-5m"|jq -r '.results[].page.url'|uniq
# Retrieve all scans performed by your own team over the past 24 hours
urlscan search "team:me AND date:>now-24h" --all
Hostnames & Domains
# List unique hostnames first seen over the past 30 days which contain a specific keyword.
urlscan search --datasource hostnames "domain_words:urlscan AND first_seen:>now-30d"|jq -r '.results[].hostname'
# List recent second-level (registered) domains containing the keyword "bank"
urlscan search --datasource hostnames "domain_words:bank AND first_seen:>now-30d AND tags:apexdomain"|jq -r '.results[].hostname'
Please refer to the README for more details. We’re thrilled to bring this powerful new tool to our users. As we are constantly striving to improve our product, we would love to get your feedback on our new CLI. For any suggestions about improvements or further functionality as well as general support and bug reporting, please reach out to our support team at support@urlscan.io or open a GitHub issue in the urlscan-cli Github project.
More on urlscan Pro
If you want to learn about the urlscan Pro platform and how it might be valuable for your organization, take a look at our urlscan Pro product page or feel free to reach out to us! We offer free trials with no strings attached. We would be happy to give you a passionate demo of what our platform can do for you. Reach out to us at sales@urlscan.io.
Get started today
Start a free 30-day trial or talk to our sales team about a plan for your organization.