Skip to content
Get packs

Guide · Agent skill

How to use the urlscan.io malicious URL analysis skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

This guide explains how to install and use the analyzing-malicious-url-with-urlscan agent skill, which gives an AI agent a structured procedure for investigating suspicious links with urlscan.io. It is written for people who have not used agent skills before. By the end you will know what the skill does, how to set it up, how to ask for it in plain language, and where its limits are.

Analyzing Malicious URLs with urlscan.iomukul975/Anthropic-Cybersecurity-Skills · Apache-2.0

Quick start

  1. 1Get your urlscan.io key. Create a urlscan.io account and copy your API key. The source notes that a free tier is available with an API key for automation.
  2. 2Set the environment variables. Set URLSCAN_API_KEY to your key. Optionally set VT_API_KEY if you want VirusTotal cross-referencing.
  3. 3Install Python and requests. Make sure Python 3.8 or newer is available with the requests library installed, using your usual setup method.
  4. 4Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or the project's .claude/skills/ folder for one project.
  5. 5Ask the agent to investigate a link. Describe the suspicious URL and what you want back, such as a screenshot review, redirect chain or IOC list.
  6. 6Review the results. Check the screenshot, redirects, forms, network requests and certificate, then note the IOCs in the report template.
  7. 7Cross-check before acting. Compare findings with other threat intelligence services, since the skill suggests this and a scan result alone is not proof.

What the skill makes the agent do

urlscan.io is a free service for scanning and analyzing suspicious URLs. It loads a page in an isolated environment and records screenshots, DOM content, HTTP transactions, JavaScript behavior and network connections. The skill tells the agent to follow a fixed investigation procedure using that service, so the analysis is repeatable rather than improvised.

  • Submit a suspicious URL to urlscan.io as a scan.
  • Review the screenshot for brand impersonation, the redirect chain and the final destination.
  • Check the DOM for credential input forms, the network requests for data-exfiltration endpoints, and the SSL certificate's validity and issuer.
  • List indicators of compromise such as domains, IPs, URLs and SHA-256 hashes of page resources.
  • Suggest cross-checking findings against other threat intelligence sources such as VirusTotal, PhishTank and Google Safe Browsing.

Install the skill with a ZIP file or the Claude apps

You can install the skill in one of three ways. For a personal setup, download the ZIP from this page and unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

After installing, the folder should contain SKILL.md, scripts/agent.py, scripts/process.py, references/ and assets/template.md.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/
  • Claude apps: Settings → Capabilities → Skills, then upload

Set up the requirements

The skill needs a urlscan.io account and an API key, which the scripts read from the URLSCAN_API_KEY environment variable. You also need Python 3.8 or newer with the requests library. A VirusTotal API key in the VT_API_KEY environment variable is optional and only used for cross-referencing.

The source does not give installation commands for Python or requests, so use your usual method for your system.

  • urlscan.io account and API key, set as URLSCAN_API_KEY
  • Python 3.8+ with the requests library
  • Optional: VirusTotal API key, set as VT_API_KEY
export URLSCAN_API_KEY=your-api-key

Ask for the skill with natural requests

You do not need to type the skill name. Describe the task in plain language and mention the link. The agent should pick up the skill when the request matches its purpose of investigating a suspicious URL.

Good requests say what you want back, such as a screenshot review, a redirect chain, or an IOC list. Be aware that submitting a URL sends it to the public service unless you keep the scan private.

  • Investigate this link a user reported and tell me whether it imitates a bank login page.
  • Scan this URL with urlscan.io and document the full redirect chain.
  • Pull the domains, IPs and file hashes from this suspicious link's scan and list them as IOCs.
  • Check this URL against urlscan.io and VirusTotal and summarize where the sources agree.

Use the bundled scripts and report template

The bundled scripts/process.py is described in the source as automating URL scanning, IOC extraction and cross-referencing. scripts/agent.py and the API reference show how submissions and result retrieval work. The source's submission example sends the URL with visibility set to private, and the API accepts public, unlisted or private.

The assets/template.md file is a report template with sections for URL details, page analysis, TLS certificate, redirect chain, threat intelligence cross-reference and extra IOCs. It also includes a defanged URL field, which lets you write links into a report without making them clickable.

  • scripts/process.py: scan, extract IOCs and cross-reference
  • scripts/agent.py: part of the agent workflow
  • references/api-reference.md: endpoints and search syntax
  • references/workflows.md and references/standards.md: workflow and MITRE ATT&CK references
  • assets/template.md: report template
POST https://urlscan.io/api/v1/scan/ API-Key: your-api-key {"url": "https://suspicious-url.com", "visibility": "private"}

Safety notes before you scan

This skill runs scripts and uses the network. Read the bundled scripts before running them, and check what they send and where. The public urlscan.io service may make submissions visible to others unless they are kept private, and the target site may see the scanner. Do not submit sensitive or internal URLs to the public service.

A scan result is a signal, not proof. The skill does not itself verify that a link is safe. Treat results as one input to an investigation, and cross-check them before acting.

  • Do not scan internal or sensitive URLs with the public service.
  • Keep scans private where possible; the skill's example uses private visibility.
  • Review scripts before running them because the skill executes Python.
  • Never treat a clean-looking scan as confirmation that a link is safe.

What people use it for

  • Triaging phishing reports from users by checking whether the page imitates a known login page.
  • Documenting the full redirect chain of a link found in a suspicious email.
  • Building a list of domains, IPs and file hashes contacted by a suspicious page for a SOC case.
  • Starting a template for an automated URL-checking pipeline using the bundled Python scripts.

Frequently asked questions

Is the urlscan.io analysis skill free?

The source describes urlscan.io itself as a free service and says a free tier is available with an API key for automation. The source does not state pricing for other tiers, so check urlscan.io for current terms.

What do I need to run this skill?

You need a urlscan.io account and API key set as URLSCAN_API_KEY, plus Python 3.8 or newer with the requests library. A VirusTotal key in VT_API_KEY is optional.

Where do I put the skill folder?

Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

Does this skill confirm that a link is safe?

No. The source states that scan results are a signal, not proof, and that the skill does not itself verify safety. Use the findings alongside other threat intelligence before deciding.

Are my scans private?

The skill's example submission uses visibility private, but the source warns that public submissions may be visible to others. Do not scan sensitive or internal URLs with the public service.

What are the alternatives to urlscan.io for this?

The skill's references list VirusTotal, PhishTank, Google Safe Browsing, Any.Run and Hybrid Analysis. The source does not compare them on features or accuracy, so the choice is up to you.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits SOC analysts, email security staff and developers who want a structured, repeatable way to investigate suspicious links with urlscan.io. It is not a safety verdict tool, so anyone who needs confirmation that a link is safe, or who must scan sensitive internal URLs, should pick a different approach or keep the work away from the public service.

Download the skill