Authorized Web Exposure Audit

A conservative, authorization-first skill for finding accidental exposure on a website’s public surface. It reviews a small set of public pages, API documentation paths, same-origin JavaScript bundles, document references, and response headers without attempting authentication bypasses or retrieving private records.

The project works as a reusable skill in both Codex and Claude Code and includes a deliberately vulnerable localhost fixture for safe demonstrations.

Download the latest release · Sanitized sample findings

Why this project exists

Modern web applications often expose more client-side information than teams intend: an OpenAPI document left public, an endpoint referenced in a bundle, a secret-like value embedded during a build, a document listed in a sitemap, or an unsafe header combination. This tool provides a repeatable way to review those signals while maintaining strict authorization and evidence-minimization boundaries.

It is not a vulnerability scanner, exploit framework, paywall bypass tool, or substitute for a professional penetration test.

Highlights

• Requires a written scope file for every non-loopback target.
• Allows localhost demonstrations without external network traffic.
• Uses unauthenticated GET requests only.
• Stays on exact approved hosts, schemes, ports, and path prefixes.
• Rejects percent-encoded, backslash, and dot-segment paths to avoid ambiguous server-side path normalization.
• Never fetches discovered API endpoints, document links, source maps, or private-looking routes.
• Redacts suspected secrets and records only a short fingerprint.
• Enforces request, rate, timeout, body-size, and error ceilings.
• Stops on login forms, sensitive-data indicators, blocking, instability, or out-of-scope redirects.
• Produces machine-readable JSON and a concise Markdown report.
• Uses only the Python standard library.

Safety model

flowchart LR
    A[Target requested] --> B{Loopback target?}
    B -->|Yes| C[Local fixture mode]
    B -->|No| D{Valid approved scope?}
    D -->|No| E[Refuse network traffic]
    D -->|Yes| F[Dry-run request plan]
    C --> F
    F --> G[Bounded public GET requests]
    G --> H{Stop condition?}
    H -->|Yes| I[Stop and retain minimal metadata]
    H -->|No| J[Redacted structured findings]

Authorization is part of the design, not a disclaimer added afterward. Saying “I work there” or “this is only a test” is not sufficient authorization for a production system. Use the included localhost fixture, a system you control, or a target covered by explicit written permission or a published security-testing program.

Checks performed

Area	What the tool checks	What it does not do
API documentation	Fixed common public documentation paths and content indicators	Enumerate arbitrary paths or call documented endpoints
JavaScript	Same-origin scripts referenced by retrieved pages	Fetch source maps or third-party bundles
Secrets	High-confidence token and assignment patterns	Print, validate, or use suspected credentials
Documents	Links found in public pages, robots metadata, and sitemaps	Download or inspect linked documents
Headers	Selected security, caching, and CORS headers	Attempt browser-policy bypasses
Access control	Obvious unauthenticated availability on approved public paths	Guess identifiers, log in, bypass controls, or access records

Quick start: safe localhost demonstration

Requires Python 3.9 or newer. No third-party packages are needed.

Start the fake vulnerable site:

python3 scripts/demo_server.py --port 8765

In a second terminal, preview the request plan without sending traffic:

python3 scripts/audit_site.py http://127.0.0.1:8765/ --dry-run

Run the local audit:

python3 scripts/audit_site.py \
  http://127.0.0.1:8765/ \
  --output-dir demo-output

The fixture contains fake data only. Expected findings include public API documentation, endpoint references, a redacted fake secret, public-document references, and a deliberately risky CORS configuration.

For example, a run against the fixture produced this excerpt in findings.md:

Requests: 9 (limit 30)
Stop reason: Completed planned requests

F-004: API documentation is publicly reachable
  Severity: informational; confidence: high
  Public availability may be intentional; confirm expected state with the owner.

F-006: Suspected assigned secret-like value in public client content
  Severity: high; confidence: medium
  Pattern match only; value was not tested or reproduced in output.

The numbers and findings depend on the target and settings. This example is from the fake localhost fixture, not a live organization's site. The full report includes redacted evidence and observations; an endpoint reference or public document is not automatically a vulnerability.

Installing as a skill

Keep the entire folder together.

For Codex, place it at:

$CODEX_HOME/skills/authorized-web-exposure-audit

If CODEX_HOME is unset, use ~/.codex/skills/authorized-web-exposure-audit.

For Claude Code, place it at either:

.claude/skills/authorized-web-exposure-audit
~/.claude/skills/authorized-web-exposure-audit

Restart the relevant client if it does not detect the skill immediately.

Authorized non-local use

Do not run the tool against a production or third-party system until the organization has approved the exact scope. The scope records:

• Organization and authorizer
• Exact scheme, hostname, and port
• Allowed and excluded path prefixes
• Validity window
• Request and rate ceilings
• Security contact

See references/scope-format.md for the schema. Always run --dry-run first:

python3 scripts/audit_site.py \
  https://audit.example.com/ \
  --scope approved-scope.json \
  --dry-run \
  --output-dir audit-output

After a human confirms that the plan exactly matches the written approval, repeat without --dry-run.

Output

• findings.json contains structured run metadata, observations, redacted findings, and the stop reason.
• findings.md is a concise review copy.

The scanner does not retain response bodies. URLs and response headers can still be sensitive in context, so review reports before sharing them.

See examples/sample-findings.md for a stable, sanitized example and references/findings-template.md for the full reporting structure.

Project structure

authorized-web-exposure-audit/
├── SKILL.md                         Agent workflow and safety boundaries
├── agents/openai.yaml               Codex interface metadata
├── scripts/audit_site.py            Scope-aware audit helper
├── scripts/demo_server.py           Local fake vulnerable site
├── references/scope-format.md       Approved-scope schema
├── references/findings-template.md  Reporting template
├── references/setup-and-examples.md Detailed operating instructions
├── examples/sample-findings.md      Sanitized example output
└── PORTFOLIO.md                     Concise project case study

Limitations

• Pattern matching can produce false positives and false negatives.
• Public availability alone does not prove unintended exposure.
• The tool does not validate exploitability, credential validity, authorization boundaries, or business impact.
• It intentionally sacrifices coverage for predictable, low-impact behavior.
• It cannot determine whether a named authorizer has legal authority; the operator must verify that independently.

Responsible use

If the tool identifies a suspected active secret or sensitive-data exposure, do not test it. Preserve minimal evidence, notify the approved security contact, recommend containment, and obtain separate permission before retesting. The complete workflow is in SKILL.md.

Contributing and security

See CONTRIBUTING.md before proposing changes. Report vulnerabilities in this tool according to SECURITY.md. Do not include live secrets, customer records, or unauthorized target data in issues or pull requests.

License

Released under the MIT License. The license covers this software, not permission to test systems you do not control.