The Complete Production SOP: How to Deploy and Run SSRF Defense & Private IP Address Blocker in Autonomous AI Agents
Production SOP to install and run the SSRF Defense skill in Codex, Claude Code, Cursor, and Windsurf. Block RFC 1918, link-local, and cloud metadata access.
Technical Overview & Architectural Context
Autonomous coding agents like Codex, Claude Code, and Cursor frequently implement webhook listeners, scraping pipelines, and remote URL fetching utilities by directly instantiating standard HTTP clients (e.g., Axios, fetch, or Requests). By default, these standard libraries follow HTTP redirects and permit egress connections to internal network topologies, leaving services vulnerable to Server-Side Request Forgery (SSRF). Without strict procedural guardrails, an agent will often generate code that validates hostnames prior to DNS resolution, completely missing DNS rebinding attacks, IPv6-mapped IPv4 representations (e.g., ::ffff:169.254.169.254), and AWS/GCP link-local metadata endpoints. The 'ssrf-defense-private-ip-blocker' skill enforces deterministic boundaries on agent-generated code. It forces autonomous agents to reject naive string-based URL filters and mandate custom socket-level DNS pre-resolution, CIDR subnet matching across RFC 1918, loopback, and cloud metadata ranges, and the explicit disabling of client-side automated redirects. By mounting this skill, engineering teams ensure that any network fetching logic authored by LLM agents complies with hardened SecOps standards out of the box.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into the agent runtime directory.
Autonomous runtimes parse skill manifests from ~/.agents/skills/ or workspace .agents/ directories. To mount the 'ssrf-defense-private-ip-blocker' skill, download the validated SKILL.md into the runtime path. The agent inspects the frontmatter triggers ('prevent ssrf attack', 'block private ip range fetch', 'protect aws metadata endpoint 169.254.169.254') to dynamically hook into prompts requesting external network requests or webhook dispatchers.
mkdir -p .agents/skills/ssrf-defense-private-ip-blocker && curl -fsSL https://askills.dev/api/skills/ssrf-defense-private-ip-blocker/raw -o .agents/skills/ssrf-defense-private-ip-blocker/SKILL.md---
name: "ssrf-defense-private-ip-blocker"
description: "Protect internal microservices and cloud metadata endpoints against SSRF attacks."
metadata:
author: "OWASP"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "prevent ssrf attack"
- "block private ip range fetch"
- "protect aws metadata endpoint 169.254.169.254"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# SSRF Defense & Private IP Address Blocker SOP
1. Resolve hostnames to IP addresses prior to connecting, validating against private CIDR blocks.
2. Block private ranges: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, and 169.254.0.0/16 (including IPv6 equivalents).
3. Disable automated HTTP redirect following in client libraries.
4. Route outbound webhooks through isolated network egress proxies.Place the skill inside the project-root `.agents/skills` directory instead of global `~/.agents/` so the exact defensive validation logic is locked in git version control for all team members.
Ensure permissions in SKILL.md leave `net_access: false` and `shell_exec: false` for the skill definition itself; security skills should guide agent code generation deterministically without requesting execution rights.
Environment Secrets & Dependency Validation
Inject required IP validation libraries and verify isolated egress dependencies without leaking secrets.
Rather than letting the agent reinvent subnet masking with regex (which consistently leads to bypasses), install vetted network parsing primitives such as 'ipaddr.js' for Node.js or 'ipaddress' for Python. Verify that test configurations and proxy authentication credentials are kept in `.env.test.local` rather than inlined in generated files.
npm install ipaddr.js --save-exact || pip install ipaddressInstruct the agent in your prompt to strictly import standard CIDR parsers rather than writing bespoke regex string comparisons, eliminating 99% of octal/hex parsing bypasses.
Do not commit local mock proxy addresses or cloud credential endpoints inside your unit test fixtures.
Intent Matching & Trigger Invocation
Verify deterministic activation using tested natural language prompts matching SKILL.md triggers.
Agent runtimes monitor incoming developer prompts against the declared triggers. To deterministically invoke the skill, ensure your instructions explicitly reference webhook generation or fetching remote URLs with private IP blocking constraints. This triggers the agent to inject custom lookup handlers or custom HTTP transport agents.
Include the phrase 'protect aws metadata endpoint 169.254.169.254 and block private ip range fetch' directly in agent instructions to enforce exact SOP match.
If the agent falls back to a generic `fetch(url)` without custom DNS resolution, the trigger was not matched; confirm that `.agents/skills/` is loaded in your editor context.
Verification, Linting & Output Quality Gate
Execute automated self-healing checks to verify that SSRF test suites pass and DNS rebinding protections hold.
Execute targeted unit tests verifying that RFC 1918 IP addresses (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback addresses (127.0.0.1, ::1), and link-local metadata addresses (169.254.169.254) are rejected with a deterministic ValidationError before any socket connection opens.
npm test -- tests/ssrf-guard.test.tsCheck `git diff` to ensure the agent did not configure `maxRedirects: 5` or allow unvalidated 302 responses, which attackers exploit to pivot from a public domain to an internal link-local IP.
A mock test that only checks 'http://localhost' is insufficient. Always ensure the test suite includes hexadecimal and dotted-decimal IP variants.
Real-World Scenario: Hardening a User Avatar Remote Fetcher Against SSRF and Cloud Metadata Extraction
“Write a secure Node.js service function `fetchRemoteAvatar(url: string)` using Node fetch or http/https agents. You must prevent ssrf attack, block private ip range fetch, and protect aws metadata endpoint 169.254.169.254. Disable automatic redirects and validate resolved IPs before connecting.”
Runtime Troubleshooting & Failure Modes
Root Cause: The underlying client library (e.g., Axios or Node fetch) was configured with default redirect handling, allowing a benign public URL to return a 301/302 redirecting to AWS IMDSv1.
Set redirect policy to 'manual' or 'error' in client options: `const response = await fetch(targetUrl, { redirect: 'error' });` or configure custom redirect handling that re-resolves and re-validates the target IP on every hop.Root Cause: Custom regex failed to recognize alternative IP representations (octal, hex, or dword formats) used by attackers to circumvent simple string-based hostname filters.
Enforce DNS resolution via `dns.promises.lookup(hostname)` prior to socket creation, and validate the resulting canonical IP object with `ipaddr.parse(resolvedIp).range() !== 'unicast'`.Frequently Asked Questions (SSRF Defense & Private IP Address Blocker SOP)
Q:Can I use SSRF Defense & Private IP Address Blocker across Codex, Claude Code, and Cursor simultaneously?
Yes. This skill conforms to the universal SKILL.md specification. When placed in your workspace's `.agents/skills/` directory, any compatible runtime (Codex Desktop, Claude Code, Cursor, or Windsurf) will parse and adhere to the procedural security rules.
Q:How does SSRF Defense & Private IP Address Blocker prevent context window overflow during long agent sessions?
The skill provides concise, deterministic operational steps and pre-defined CIDR validation logic directly in the YAML frontmatter and SOP body. This prevents the agent from generating verbose, trial-and-error network code that bloats conversation history and wastes context tokens.
Q:Does this skill require escalated root or container permissions?
No. The skill is rated 98/100 on security audit score. It operates with zero privileged execution rights (`shell_exec: false`, `net_access: false`), acting purely as a deterministic coding policy guide for agent reasoning.
Ready to equip your autonomous agent with SSRF Defense & Private IP Address Blocker?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.