# jstreampro/php_surface_audit architecture

> Architecture diagram of the GitHub repository jstreampro/php_surface_audit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jstreampro/php_surface_audit
- Repository: https://github.com/jstreampro/php_surface_audit

## Overview

PHP Surface Audit is a bounded, evidence-driven PHP exposure scanner for approved IPs, DNS names, and URLs. Its principal workflow normalizes targets and scope, resolves and probes them over HTTP(S), discovers in-scope routes and host identities, compares responses for PHP indicators, then classifies evidence and emits review reports. The README also documents configurable concurrency and request budgets, optional enhanced DNS, and CVE-version review. The implementation is a single large module; the excerpts show key stages but not every internal call, so uncertain wiring is omitted.

Main entry points: [`php_surface_audit.py`](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py) (Target auditor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Scan orchestration"]
  node_cli["CLI and config"]
  node_auditor["Target auditor"]
  node_target["Target parsing"]
  node_scope["Scope policy"]
end

subgraph group_network["Network and discovery"]
  node_resolver["DNS resolver"]
  node_rate["Rate limiter"]
  node_http["HTTP probes"]
  node_redirect["Redirect handling"]
  node_discovery["Page discovery"]
  node_identity["Host candidates"]
  node_controls["Route controls"]
end

subgraph group_analysis["Evidence analysis"]
  node_evidence["Evidence detection"]
  node_classification["Finding classification"]
  node_version["Version review"]
  node_coverage["Coverage notes"]
end

subgraph group_output["Review outputs"]
  node_records[("Observation evidence")]
  node_reports["HTML CSV JSON"]
end

node_operator(("Authorized operator"))
node_web(("Target web service"))
node_optional_dns["dnspython"]

node_operator -->|"supplies targets"| node_cli
node_cli -.->|"parses inputs"| node_target
node_cli -.->|"starts scan"| node_auditor
node_auditor -.->|"checks scope"| node_scope
node_auditor -.->|"resolves names"| node_resolver
node_auditor -.->|"requests pages"| node_http
node_auditor -.->|"limits requests"| node_rate
node_http -->|"sends GET"| node_web
node_auditor -->|"follows redirects"| node_redirect
node_auditor -->|"queues links"| node_discovery
node_discovery -.->|"filters links"| node_scope
node_auditor -.->|"records candidates"| node_identity
node_auditor -.->|"compares routes"| node_controls
node_auditor -->|"observes responses"| node_evidence
node_evidence -.->|"supports findings"| node_classification
node_classification -->|"assesses reports"| node_version
node_auditor -->|"records gaps"| node_coverage
node_auditor -.->|"saves evidence"| node_records
node_auditor -.->|"generates reports"| node_reports
node_resolver -.->|"uses optionally"| node_optional_dns

click node_cli "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_auditor "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_target "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_scope "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_resolver "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_rate "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_http "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_redirect "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_discovery "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_identity "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_controls "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_evidence "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_classification "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_version "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_coverage "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_records "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"
click node_reports "https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_auditor,node_target,node_scope toneBlue
class node_resolver,node_rate,node_http,node_redirect,node_discovery,node_identity,node_controls toneAmber
class node_evidence,node_classification,node_version,node_coverage toneMint
class node_records,node_reports toneRose
class node_operator,node_web,node_optional_dns toneIndigo
```

## Components

### Scan orchestration

- [CLI and config](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [Target auditor](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [Target parsing](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [Scope policy](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`

### Network and discovery

- [DNS resolver](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [Rate limiter](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [HTTP probes](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [Redirect handling](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [Page discovery](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [Host candidates](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [Route controls](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`

### Evidence analysis

- [Evidence detection](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [Finding classification](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [Version review](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [Coverage notes](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`

### Review outputs

- [Observation evidence](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`
- [HTML CSV JSON](https://github.com/jstreampro/php_surface_audit/blob/main/php_surface_audit.py): `php_surface_audit.py`

### Other components

- **Authorized operator**
- **Target web service**
- **dnspython**

## Connections

- Authorized operator → CLI and config: supplies targets (evidence: `README.md`)
- CLI and config → Target parsing: parses inputs (evidence: `php_surface_audit.py`)
- CLI and config → Target auditor: starts scan (evidence: `php_surface_audit.py`)
- Target auditor → Scope policy: checks scope (evidence: `php_surface_audit.py`)
- Target auditor → DNS resolver: resolves names (evidence: `php_surface_audit.py`)
- Target auditor → HTTP probes: requests pages (evidence: `php_surface_audit.py`)
- Target auditor → Rate limiter: limits requests (evidence: `php_surface_audit.py`)
- HTTP probes → Target web service: sends GET (evidence: `README.md`)
- Target auditor → Redirect handling: follows redirects (evidence: `php_surface_audit.py`)
- Target auditor → Page discovery: queues links (evidence: `php_surface_audit.py`)
- Page discovery → Scope policy: filters links (evidence: `php_surface_audit.py`)
- Target auditor → Host candidates: records candidates (evidence: `php_surface_audit.py`)
- Target auditor → Route controls: compares routes (evidence: `php_surface_audit.py`)
- Target auditor → Evidence detection: observes responses (evidence: `php_surface_audit.py`)
- Evidence detection → Finding classification: supports findings (evidence: `php_surface_audit.py`)
- Finding classification → Version review: assesses reports (evidence: `php_surface_audit.py`)
- Target auditor → Coverage notes: records gaps (evidence: `php_surface_audit.py`)
- Target auditor → Observation evidence: saves evidence (evidence: `php_surface_audit.py`)
- Target auditor → HTML CSV JSON: generates reports (evidence: `php_surface_audit.py`)
- DNS resolver → dnspython: uses optionally (evidence: `README.md`)
