ERSEC 20.0.0

Evidence-Driven Application Security Platform

ERSEC is a defensive web and application-security platform designed to go beyond the traditional model of crawl → probe → list vulnerabilities.

At its core, ERSEC still performs responsible, non-destructive security testing. But the current system also builds a model of the application, reasons about security boundaries, correlates findings into attack paths, compares security behavior across identities and representations, tracks drift between scans, generates remediation and policy artifacts, and compiles a local security-control state that can be used as a release or regression signal.

ERSEC is intentionally designed for environments where the operator wants:

• broad application-security coverage without destructive exploitation;
• evidence-backed findings instead of unsupported guesses;
• repeatable verification of previously observed issues;
• offline-first analysis and a built-in deterministic remediation advisor;
• local security memory and cross-run regression detection;
• developer-oriented remediation, policy-as-code, and IDE scaffolding;
• a single machine-readable security state that can evolve with the application.

Version: 20.0.0

Detector registry: 73 registered detector definitions in this release

Intelligence/control engines: 31 capability areas exposed by the runtime capability manifest

Security model: authorized, bounded, non-destructive testing for assessment; explicit defensive enforcement mode for Shield

---

What makes ERSEC different?

Traditional scanners are optimized around a list of checks. ERSEC is increasingly optimized around a list of security questions:

What is exposed?

What behavior is inconsistent?

Which security boundary changes when the request, identity, method, representation, or path changes?

Which findings combine into a realistic risk chain?

What security assumptions does the application appear to rely on?

What changed since the previous scan?

Which controls should become explicit tests or release gates?

That leads to a layered architecture:

                    ┌──────────────────────────┐
                    │       ERSEC 20.0         │
                    │ Application Security     │
                    │        Platform          │
                    └────────────┬─────────────┘
                                 │
             ┌───────────────────┼───────────────────┐
             │                   │                   │
             ▼                   ▼                   ▼
       Discovery &          Detection &         Evidence &
       Contract Mining      Differentials        Verification
             │                   │                   │
             └───────────────────┼───────────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │   Reasoning & Fusion    │
                    │ workflows / graphs /    │
                    │ causal + metamorphic    │
                    └────────────┬────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │ Security Control Plane  │
                    │ assets / hypotheses /   │
                    │ exposure / SLO / drift  │
                    └────────────┬────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │ Developer / Governance  │
                    │ remediation / policies  │
                    │ IDE / reports / proofs  │
                    └─────────────────────────┘

ERSEC does not claim that a scan proves an application is secure or that it can find every possible vulnerability. Its goal is to maximize useful, reproducible evidence while keeping active testing bounded and non-destructive.

---

Major capabilities in ERSEC 20

ERSEC Shield: from scanner to enforcement point

ERSEC 20 introduces ERSEC Shield, a local defensive reverse proxy that turns selected ERSEC evidence into runtime guardrails.

The design is intentionally influenced by two established ideas: NIST's zero-trust architecture places a policy enforcement point between subjects and protected resources, while OWASP describes virtual patching as a risk-reduction control rather than a replacement for fixing the underlying vulnerability.

ERSEC Shield is therefore not marketed as a magical firewall that understands every application. It is a deliberately bounded application-security enforcement point that can:

• proxy authorized application traffic to an upstream service;
• operate in monitor, block, or learn mode;
• enforce request-body and URL-size limits;
• enforce an HTTP method allow-list;
• apply per-source rate and burst limits;
• reject ambiguous request framing;
• detect selected path-normalization anomalies;
• enforce narrow, high-confidence virtual patches generated from ERSEC findings;
• keep lower-confidence findings in monitoring rather than automatically turning them into hard blocks;
• record privacy-minimized JSONL decision telemetry;
• learn route/method shapes without storing request bodies;
• optionally terminate TLS at the Shield edge;
• compile a prior ERSEC JSON report into a portable Shield policy.

This is the architectural loop:

Application
    │
    ▼
ERSEC discovery + detection
    │
    ├── evidence
    ├── security boundaries
    ├── findings
    ├── attack paths
    └── control-plane state
    │
    ▼
Shield Policy Compiler
    │
    ├── narrow virtual patches
    ├── route controls
    ├── method controls
    └── resource/rate controls
    │
    ▼
ERSEC Shield (Policy Enforcement Point)
    │
    ├── monitor
    ├── block
    └── learn
    │
    ▼
upstream application
    │
    ▼
telemetry + security state
    │
    └──────────────→ next ERSEC scan / regression analysis

Start Shield in block mode

python3 ersec.py \
  --shield \
  --shield-upstream http://127.0.0.1:8000 \
  --shield-bind 127.0.0.1 \
  --shield-port 8080 \
  --shield-mode block \
  --shield-log .ersec-shield.jsonl

The default listen address is 127.0.0.1 on purpose. Exposing a new gateway publicly should be an intentional deployment decision with appropriate TLS and network controls.

Monitor before block

For a newly deployed policy, begin with:

python3 ersec.py \
  --shield \
  --shield-upstream http://127.0.0.1:8000 \
  --shield-mode monitor \
  --shield-log .ersec-shield.jsonl

Monitor mode records matching policy decisions without turning those virtual-patch matches into a gateway denial.

Learn route shapes

Learning mode records URL-path/method/status observations while deliberately avoiding request-body persistence:

python3 ersec.py \
  --shield \
  --shield-upstream http://127.0.0.1:8000 \
  --shield-mode learn \
  --shield-learning .ersec-shield-learning.json

The learning file is intended to become an operator-reviewed input for future positive-security policy work. ERSEC does not silently convert arbitrary observations into a production allow-list.

Generate virtual patches from a scan

Compile a prior ERSEC report:

python3 ersec.py \
  --shield-compile ersec-report.json \
  --shield-policy ersec-shield-policy.json

Or start Shield directly from the report:

python3 ersec.py \
  --shield \
  --shield-upstream http://127.0.0.1:8000 \
  --shield-from-report ersec-report.json \
  --shield-policy ersec-shield-policy.json

The compiler deliberately restricts automatic blocking to findings with sufficiently strong deterministic evidence. A Possible observation is not automatically treated as a production-deny rule.

Shield safety model

Shield is a defensive control, but bad blocking rules can still create an availability problem. For that reason:

• virtual patches are narrow and path-scoped;
• lower-confidence findings default to monitoring;
• rate/resource limits are explicit and configurable;
• request bodies are not stored by the learning subsystem;
• source addresses in telemetry are hashed before logging;
• the gateway binds to localhost by default;
• Shield does not execute application code or attempt offensive post-exploitation.

A virtual patch is a compensating control. It is not the same thing as fixing the vulnerable application logic. OWASP explicitly recommends viewing virtual patching as risk reduction and warns against assuming that an exploit-specific block is a complete fix.

Runtime controls

Current Shield controls include:

Control	Function
Request-size guard	Caps request body bytes
URL guard	Caps URL length
Method policy	Blocks methods outside the configured allow-list
Rate guard	Sustained per-source request ceiling
Burst guard	Short-window per-source burst ceiling
Framing guard	Rejects ambiguous Content-Length + Transfer-Encoding combinations
Path guard	Detects selected traversal/normalization anomalies
Virtual patches	Applies finding-derived parameter/path rules
TLS edge	Optional TLS termination with operator-supplied certificate/key
Telemetry	JSONL decision events with minimized identity data
Learning	Route/method/status shape collection without body storage

Why this matters for API security

The move from scanner to enforcement point is especially valuable for APIs. OWASP's API Security Top 10 continues to emphasize authorization, unrestricted resource consumption, sensitive business flows, SSRF, inventory management, and unsafe consumption of APIs. ERSEC's scanner-side engines already model several of these concerns; Shield adds a place where a subset of the resulting controls can be enforced continuously at the application edge.

The aim is not to claim that a reverse proxy can solve API security by itself. Authorization failures, business-logic flaws, unsafe downstream integrations, and application-specific invariants frequently require application-level fixes and identity-aware controls.

ERSEC 20 architecture

ERSEC 20 can now be thought of as five connected layers:

1. OBSERVE
   crawler / browser / API discovery / code scan

2. UNDERSTAND
   detectors / differential analysis / identity workflows /
   behavioral memory / security genome / contract drift

3. REASON
   risk graphs / attack paths / causal analysis /
   metamorphic analysis / decision lattice / adaptive planning

4. GOVERN
   Security Control Plane / exposure budget / hypotheses /
   security SLO / cross-run regression state

5. ENFORCE
   ERSEC Shield / virtual patches / rate & resource guards /
   route learning / runtime security telemetry

This is the main conceptual change in ERSEC 20: findings can become controls, controls can generate runtime evidence, and runtime evidence can feed the next security-state comparison.

1. Autonomous discovery and application mapping

ERSEC does not depend exclusively on a manually supplied list of URLs.

The discovery layer can combine:

• same-origin crawling;
• robots.txt discovery;
• sitemap.xml discovery;
• HTML links and forms;
• JavaScript and same-origin script references;
• API-like route discovery;
• optional browser/Playwright traffic discovery for SPAs;
• API contract/specification mining;
• adaptive endpoint and parameter planning;
• passive surface mining.

When browser automation is unavailable, ERSEC can fall back to static/API-oriented discovery instead of treating a missing local browser runtime as a fatal condition.

The objective is to discover the security-relevant surface before spending testing budget on it.

---

2. Evidence-backed detection

ERSEC contains a broad detector registry covering web, API, browser, authentication, configuration, and parser-differential conditions.

The current registry includes signals for areas such as:

Authentication, authorization, and access control

• unauthenticated admin/management exposure;
• object-authorization/IDOR heuristics;
• multi-identity workflow replay;
• HTTP-method authorization differences;
• content-negotiation authorization differences;
• observed-object authorization checks;
• authenticated response-cache exposure;
• OAuth/OIDC state validation signals;
• password-recovery/reset-token leakage;
• weak or predictable session tokens;
• sensitive cookie scope and cookie-path issues;
• rate-limiting signals on sensitive endpoints.

Injection and input handling

• SQL injection signals;
• NoSQL injection signals;
• LDAP injection signals;
• XPath injection signals;
• server-side template injection signals;
• command-injection timing signals;
• path traversal/normalization signals;
• CRLF/HTTP response-splitting signals;
• HTTP parameter pollution;
• structured parameter-shape differentials;
• JSON parser/duplicate-key differentials;
• API content-type and representation confusion;
• prototype-pollution signals;
• XML external entity processing signals.

Browser and client-side security

• reflected XSS signals;
• DOM XSS sink signals;
• DOM open-redirect data flow;
• weak postMessage origin validation;
• client-side credential/secret leakage;
• exposed source maps;
• service-worker security exposure;
• missing or inconsistent Subresource Integrity;
• third-party library risk signals;
• mixed content;
• clickjacking/security-header inconsistencies.

API and data exposure

• GraphQL introspection exposure;
• sensitive GraphQL schema fields;
• sensitive API response fields;
• excessive API data exposure;
• API error leakage;
• API method/framework leakage;
• API response consistency anomalies;
• API version security drift;
• backup/editor artifacts;
• exposed sensitive files and paths;
• directory listing;
• sensitive response headers;
• HTML comment information disclosure;
• verbose errors and stack traces.

Transport and application configuration

• security-header misconfiguration;
• security-header drift;
• TLS/SSL configuration signals;
• dangerous HTTP methods;
• CORS misconfiguration;
• CORS preflight inconsistency;
• insecure forms;
• forwarded-host trust;
• Host-header injection;
• cache-control weaknesses;
• web cache deception signals;
• WebSocket exposure;
• email anti-spoofing DNS signals;
• dangling CNAME/subdomain takeover signals;
• missing security.txt;
• server/framework banner disclosure.

ERSEC intentionally distinguishes between a signal and a proven exploit. Many detectors report behavioral evidence that warrants review instead of pretending that a single probe is equivalent to a weaponized exploit chain.

---

3. Behavioral and differential security analysis

One of ERSEC's central ideas is that many modern vulnerabilities are not visible as a single obviously bad response. They appear when two requests that should have the same security boundary produce meaningfully different behavior.

ERSEC therefore includes several differential techniques, including analysis across:

• HTTP methods;
• URL/path representations;
• parameter shapes;
• JSON structures;
• content types;
• API versions;
• security headers;
• cookies and cookie scope;
• authentication identities;
• content negotiation;
• response fields;
• API response behavior.

This is useful for finding security-boundary inconsistencies that are easy to miss with a simple list of payload checks.

---

4. Multi-identity and workflow reasoning

A security control can look correct in isolation and still fail across a real application journey.

ERSEC can model and replay bounded, observed workflows across explicitly authorized identities. The feature is intended for testing situations such as:

anonymous  → user
user       → admin
user       → another user
tenant A   → tenant B

The workflow layer looks for differences in authorization outcomes while preserving the platform's non-destructive testing boundary.

This allows ERSEC to reason about questions such as:

• does the same object remain accessible across identities?
• does authorization change when the HTTP method changes?
• does a workflow step become accessible after a state transition?
• does a representation or content type bypass an authorization decision?

ERSEC does not require users to provide identities that they are not authorized to use. Operators explicitly provide credentials/tokens for the identities they intend to test.

---

5. Security Decision Lattice and response anomaly reasoning

ERSEC 20 includes higher-level reasoning layers that attempt to classify security decisions rather than simply compare raw response bodies.

These layers can combine signals from:

• status codes;
• headers;
• response size and structure;
• content types;
• identity context;
• path and method;
• parameter shape;
• discovered object identifiers;
• workflow state;
• previously observed security behavior.

The purpose is to identify security decision anomalies and reduce the chance that a meaningful difference is lost inside a noisy response comparison.

This is still deterministic/heuristic analysis. It is not presented as a magical neural model that understands the application perfectly.

---

6. Attack-path and risk-graph fusion

ERSEC can correlate individually moderate findings into higher-risk combinations.

Examples include relationships such as:

XSS signal
   +
weak cookie/session controls
   ↓
possible session-impact chain

or:

sensitive object endpoint
   +
identity differential
   +
workflow exposure
   ↓
authorization risk path

The graph-based layers can also account for operator-defined crown jewels, such as:

• /admin
• /account
• /checkout
• payment or identity-management APIs
• other business-critical routes

This lets the platform prioritize findings according to their relationship to high-value application assets rather than severity labels alone.

---

7. Causal-impact reasoning

ERSEC includes bounded causal-impact analysis intended to ask:

If this observed security control changes, what other behavior or risk relationships become relevant?

This is used as a reasoning aid for impact and prioritization. It should not be interpreted as a claim that ERSEC has proven real-world business impact without application-specific validation.

---

8. Bounded autonomous security-agent planning

ERSEC contains a bounded adaptive-agent layer for selecting additional security questions from observed evidence.

Important distinction:

Autonomous does not mean unrestricted exploitation.

Agent actions remain subject to the scanner's scope, request budget, method controls, timeout controls, and non-destructive testing philosophy.

The agent layer is designed to decide which additional bounded checks are useful after the application has already revealed a relevant clue.

---

9. Metamorphic security analysis

ERSEC can generate bounded metamorphic comparisons where an application is expected to preserve a security property while a request is changed in a controlled way.

Examples of metamorphic dimensions include:

• parameter representation;
• structured input shape;
• method;
• representation/content type;
• URL/path normalization;
• API version;
• identity context.

The important output is not merely "request B returned a different response". The reasoning layer tries to determine whether that difference is relevant to a security invariant.

---

10. Security behavior genome and temporal memory

ERSEC can persist a local representation of observed security behavior across scans.

This provides a foundation for detecting changes such as:

Previous scan
    │
    ├── endpoint existed
    ├── auth behavior observed
    ├── security headers observed
    └── finding resolved

                    ↓ change

Current scan
    │
    ├── new endpoint
    ├── different auth behavior
    ├── header drift
    └── previously resolved finding reappears

The intent is to turn a one-time scan into a security regression system rather than repeatedly starting from zero.

---

11. Contract drift and API security drift

ERSEC tracks discovered API behavior and compares it across versions/runs where enough evidence exists.

The drift layer can identify changes involving:

• newly exposed API routes;
• removed routes;
• API-version differences;
• response behavior;
• security headers;
• authorization behavior;
• other contract/security-control differences.

This is especially useful when an API evolves faster than its security documentation.

---

12. Security Control Plane

ERSEC 20 introduces a larger concept than a conventional scanner: the Security Control Plane.

Instead of treating every run as an isolated report, the control plane builds a compact application-security state from the evidence collected during the scan.

It models application assets and can infer categories such as:

• privileged surfaces;
• transactional surfaces;
• identity surfaces;
• API surfaces;
• general web surfaces.

It also maintains bounded security hypotheses derived from observed application behavior.

The control plane currently includes:

Asset model

An application-security inventory derived from discovered endpoints and findings.

Hypothesis engine

A bounded queue of security questions generated from observed evidence, including authorization-boundary and workflow-related questions.

Exposure budget

A compact risk posture based on exposed assets, confirmed higher-severity findings, and critical risk chains.

Security SLO compiler

A machine-readable set of security objectives such as:

critical findings      → target 0
high findings          → target 0
coverage ratio         → target 80%+
critical attack paths  → target 0

These are posture gates produced by ERSEC's local policy model, not universal compliance requirements.

Cross-run security state

The control plane can compare the current security state with a previous snapshot and report changes such as:

• new assets;
• removed assets;
• new findings;
• resolved findings;
• new risk chains;
• resolved risk chains;
• an overall security-regression signal.

This is the point where ERSEC becomes more than a one-shot scanner: it can act as a local application-security state engine.

---

13. Evidence, proof, and deterministic re-verification

ERSEC is designed around evidence.

Findings can carry request/response evidence, contextual information, and replay metadata. The platform can also export tamper-evident proof capsules and re-run exact previously recorded probes.

Re-verification

A previous JSON report can be supplied to the re-verification workflow so ERSEC can classify the original probe as:

• still present;
• resolved;
• inconclusive.

This is different from simply running another broad scan and hoping the same detector fires.

Audit trail

ERSEC can append verification records to a hash-chained audit log and verify that log later.

This makes the verification history easier to detect when modified after the fact.

Proof and audit features are integrity aids; they are not a substitute for independent evidence preservation or a formal forensic chain of custody.

---

14. Built-in offline remediation advisor

ERSEC ships with a deterministic local remediation advisor.

The advisor is a curated expert system that can:

• map finding categories to remediation guidance;
• select stack-aware recommendations from the detected technology fingerprint;
• provide framework-specific code/configuration examples where available;
• account for correlated risk chains;
• prioritize what should be fixed first.

The built-in advisor does not require an API key and does not call a remote LLM service.

An optional local GGUF model can be used for experimental patch generation/triage when the operator has installed the relevant local runtime, but that model is not required for the core advisor.

This distinction matters:

ERSEC's default advisor is a local deterministic knowledge-based expert system, not an online generative AI service.

---

15. Remediation Twin and developer outputs

ERSEC can generate remediation-oriented artifacts intended for human review.

Available integrations include:

• framework remediation artifacts;
• Semgrep/OPA policy-as-code scaffolds;
• VS Code integration scaffolds;
• IntelliJ integration scaffolds;
• security policy artifacts;
• IDE-oriented security context.

The remediation workflow is deliberately review-oriented. ERSEC does not silently rewrite production source code and deploy it.

---

16. Code scanning and policy-as-code

ERSEC also includes a local code-engine path for scanning a supplied source tree.

This lets the platform work at multiple levels:

runtime behavior  ←→  API behavior  ←→  source code  ←→  policy

The goal is not to pretend these are identical evidence sources. They answer different questions and should be interpreted together.

---

17. Browser and SPA discovery

ERSEC can optionally use Playwright for browser/traffic discovery.

This is especially useful for applications where important routes appear only after JavaScript executes.

Because browser tooling is optional, ERSEC includes preflight/fallback behavior so a missing browser/Node installation does not have to turn the entire assessment into a hard failure.

For a browser-enabled environment:

python3 ersec.py -t https://example.com --browser --profile deep

---

18. Juice Shop benchmark and source-evidence mode

ERSEC includes a controlled OWASP Juice Shop lab adapter for local benchmarking.

Two important principles apply:

1. A challenge is not considered solved merely because a challenge catalog says it exists.
2. Where available, ERSEC can use local challenge/source evidence to build a detector-coverage view.

Example:

python3 ersec.py -t http://127.0.0.1:3000 --juice-shop-lab

This mode is intended for controlled laboratory benchmarking, not for claiming that ERSEC has solved or proven every Juice Shop challenge.

---

19. Scope enforcement and safe-testing model

Safety is an architectural property of ERSEC, not only a line in the README.

The HTTP client and scan planner enforce scope and request controls, including concepts such as:

• allowed hosts;
• allowed ports;
• allowed paths;
• allowed HTTP methods;
• request budget;
• rate limiting;
• concurrency limits;
• connection/read timeouts;
• adaptive handling of rate-limit/server-busy responses.

Active checks are intended to use bounded behavioral probes rather than destructive exploit chains.

ERSEC does not implement a general-purpose exploitation workflow for:

• data extraction;
• shell acquisition;
• persistence;
• destructive modification;
• credential theft;
• weaponized exploit chains.

A signal is not automatically a confirmed vulnerability. Operators should validate important findings in an environment where testing is explicitly authorized.

---

Installation

Minimal installation

From the ERSEC source directory:

python3 -m pip install -r requirements.txt

Core scanning is designed to operate without a remote AI service.

Optional components

Some advanced workflows are optional and environment-dependent, including browser automation and local GGUF model support.

ERSEC will not claim those capabilities are available merely because the feature exists in the code; the runtime should be checked in the operator's environment.

---

Quick start

Baseline scan

python3 ersec.py \
  -t https://example.com \
  --profile baseline \
  --output report.json \
  --html report.html

Deep scan

python3 ersec.py \
  -t https://example.com \
  --profile deep \
  --output report.json \
  --html report.html

Maximum authorized coverage

ERSEC 20 supports:

python3 ersec.py -t https://example.com -m

-m / --max enables the highest bounded coverage mode provided by the release, including the mature reasoning/control engines and opportunistic advanced discovery. Browser discovery and lab-specific capabilities remain dependent on the local target/environment.

This is maximum authorized coverage, not unlimited scanning.

---

Recommended production-style command

A more explicit assessment might look like:

python3 ersec.py \
  -t https://example.com \
  --profile deep \
  --browser \
  --crown-jewel /admin \
  --crown-jewel /account \
  --crown-jewel /checkout \
  --proof-dir .ersec-proof \
  --history-db .ersec-history.sqlite \
  --genome-memory .ersec-genome.json \
  --control-plane-memory .ersec-control-plane.json \
  --security-slo .ersec-security-slo.json \
  --patch-dir .ersec-patches \
  --policy-dir .ersec-policy \
  --ide-dir .ersec-ide \
  --output ersec.json \
  --html ersec.html \
  --sarif ersec.sarif \
  --markdown ersec.md \
  --csv ersec.csv \
  --junit ersec.xml

---

Authentication and identity-aware testing

ERSEC supports explicitly supplied authentication material for authorized assessments.

Examples:

python3 ersec.py \
  -t https://example.com \
  --cookie 'session=YOUR_AUTHORIZED_SESSION'

or:

python3 ersec.py \
  -t https://example.com \
  --bearer 'YOUR_AUTHORIZED_TOKEN'

For cross-identity workflow testing, ERSEC can accept explicitly named authorized identities:

python3 ersec.py \
  -t https://example.com \
  --identity user=USER_TOKEN \
  --identity admin=ADMIN_TOKEN \
  --identity tenantA=TENANT_A_TOKEN \
  --identity tenantB=TENANT_B_TOKEN

Only provide credentials/tokens you are authorized to use against the target.

---

Scope configuration

Use a scope file when the application surface needs to be constrained.

Conceptually, scope can control:

{
  "allowed_hosts": ["example.com"],
  "allowed_ports": [443],
  "allowed_paths": ["/", "/api", "/account"],
  "allowed_methods": ["GET", "HEAD", "POST"],
  "max_requests": 2000,
  "rate_limit_seconds": 0.15,
  "concurrency": 8,
  "timeout_seconds": 8.0,
  "max_crawl_depth": 3,
  "max_crawl_pages": 150
}

Tune these values for the environment rather than assuming that a maximum setting is appropriate for every target.

---

Profiles

passive

Focuses on non-payload-oriented observation such as:

• headers;
• TLS/certificate configuration;
• banners;
• static browser/application metadata;
• passive exposure signals.

Useful as a low-impact first look.

baseline

Adds bounded behavioral checks and common application-security detection.

deep

Enables broader input/differential checks and deeper detector coverage within configured budgets.

maximum

Used by the --max mode to activate the release's highest bounded coverage strategy.

---

Output formats

ERSEC can generate multiple report types from a single assessment.

Output	Purpose
JSON	Full machine-readable scan result
HTML	Interactive browser dashboard
SARIF	Integration with security/developer tooling
Markdown	Human-readable report
CSV	Tabular export
JUnit XML	CI/test-system integration
Proof directory	Evidence/proof capsules when enabled
Control-plane JSON	Cross-run security state
Security-SLO JSON	Compiled security objectives/gates
Policy directory	Semgrep/OPA-oriented policy artifacts
IDE directory	VS Code/IntelliJ scaffolds

The exact content depends on which features are enabled and what evidence the target exposes.

---

Re-verification

Re-run the exact recorded probes from a previous JSON report:

python3 ersec.py \
  -t https://example.com \
  --reverify previous-report.json

For an integrity-preserving audit history:

python3 ersec.py \
  -t https://example.com \
  --reverify previous-report.json \
  --audit-log verification-audit.json

Verify a prior audit log without scanning a target:

python3 ersec.py \
  --verify-audit-log verification-audit.json

---

Cross-run control plane

Persist the current application-security state:

python3 ersec.py \
  -t https://example.com \
  --control-plane-memory .ersec-control-plane.json

Write the compiled security SLO/policy representation:

python3 ersec.py \
  -t https://example.com \
  --security-slo .ersec-security-slo.json

Tune the bounded hypothesis budget:

python3 ersec.py \
  -t https://example.com \
  --hypothesis-budget 40

Disable the control plane when required:

python3 ersec.py \
  -t https://example.com \
  --no-control-plane

---

Capabilities and self-test

Show the runtime capability manifest:

python3 ersec.py --capabilities

Run the built-in offline self-test suite:

python3 ersec.py --self-test

The self-test suite exercises internal behavior such as scope enforcement, target validation, canonical identifiers, risk scoring, correlation/attack-path logic, audit-log integrity checks, and the Security Control Plane state model.

Self-tests validate the tested implementation paths; they are not proof of correctness for every possible target or environment.

---

Optional local model support

ERSEC's built-in advisor works without an external AI service.

An optional local GGUF model can be supplied for experimental local model-assisted workflows:

python3 ersec.py \
  -t https://example.com \
  --local-model /path/to/model.gguf

and, where supported by the selected feature set, a local model can also be used for evidence triage.

This remains local to the operator's environment. ERSEC's default security analysis does not require sending findings or target data to a hosted AI provider.

---

Plugin and ecosystem support

ERSEC supports local plugin loading and ecosystem scaffolding.

This allows organizations to extend detection or developer integration without modifying every built-in component.

Use the runtime capability manifest to inspect what the installed build exposes, and keep plugins subject to the same authorization and safety expectations as the core scanner.

---

CI/CD and engineering workflow

ERSEC is suitable for a workflow such as:

Developer change
      ↓
Build / deploy to test environment
      ↓
ERSEC discovery + detection
      ↓
Evidence + differential analysis
      ↓
Risk/attack-path fusion
      ↓
Security Control Plane
      ↓
SLO / regression gate
      ↓
Remediation / policy artifact
      ↓
Re-test / re-verify

The important architectural shift is that security output can become an engineering state instead of a PDF that nobody revisits.

---

Architecture at a glance

ERSECScanner
│
├── SafeHttpClient
│   ├── scope enforcement
│   ├── request budgets
│   ├── rate limiting
│   └── timeout / backoff controls
│
├── WebCrawler
│   ├── robots
│   ├── sitemap
│   ├── links/forms
│   ├── scripts
│   └── API discovery
│
├── Detector Registry
│   └── 73 registered detector definitions
│
├── Adaptive Coverage / Contract Mining
│
├── Security Differential Engines
│   ├── boundary differentials
│   ├── parameter-shape differentials
│   ├── parser differentials
│   ├── API consistency
│   ├── API-version drift
│   └── security-header drift
│
├── Identity / Workflow Engines
│   ├── observed-object authorization
│   ├── method authorization matrix
│   └── multi-identity workflow replay
│
├── Reasoning Engines
│   ├── contextual/capability risk graphs
│   ├── attack-path fusion
│   ├── decision lattice
│   ├── response anomaly ensemble
│   ├── causal impact
│   ├── bounded autonomous planning
│   └── metamorphic analysis
│
├── Longitudinal Security Memory
│   ├── behavioral memory
│   ├── security behavior genome
│   └── contract drift
│
├── Developer Security
│   ├── AdvisorEngine
│   ├── Remediation Twin
│   ├── policy-as-code
│   └── IDE scaffolds
│
└── Security Control Plane
    ├── asset model
    ├── hypothesis engine
    ├── exposure budget
    ├── security SLO compiler
    └── cross-run regression state

---

Performance and operational controls

ERSEC is designed to be configurable rather than blindly aggressive.

Key controls include:

• request budgets;
• crawl-page limits;
• worker/concurrency limits;
• per-request timeouts;
• adaptive backoff for server throttling/busy responses;
• bounded context-probe counts;
• bounded API-path retention;
• bounded autonomous-agent follow-up actions;
• bounded identity-workflow replay;
• bounded security hypotheses.

For larger targets, increase budgets deliberately and monitor the generated evidence instead of assuming that more requests always means a better assessment.

---

Accuracy philosophy

ERSEC is intentionally conservative about what it claims.

A mature security assessment should distinguish at least four things:

Observed signal
      ↓
Correlated evidence
      ↓
Verified behavioral condition
      ↓
Confirmed exploitable vulnerability

ERSEC can provide strong evidence for the first three classes, and in some cases a high-confidence finding can be produced from deterministic proof. But a non-destructive scanner should not pretend that it has demonstrated every real-world exploit path.

False positives and false negatives remain possible. Modern applications can contain business-logic, authorization, supply-chain, infrastructure, race-condition, and environment-specific vulnerabilities that no bounded scanner can completely characterize.

---

What ERSEC deliberately does not claim

ERSEC does not claim:

• that 73 detector definitions means 73 guaranteed vulnerability classes are always detectable;
• that a green scan proves an application is secure;
• that every finding is automatically exploitable;
• that every business-logic flaw can be inferred from HTTP behavior;
• that browser discovery reproduces every real user's behavior;
• that local AI/heuristics are equivalent to expert human review;
• that SLO values generated by the platform are universal compliance standards;
• that the platform replaces penetration testing, code review, threat modeling, or manual authorization testing.

This is intentional. Security tooling becomes more trustworthy when its limits are explicit.

---

Legal and authorization notice

Only run ERSEC against systems you own or systems for which you have explicit authorization to perform security testing.

Even non-destructive scanning can have operational and legal consequences. Authorization should cover the target, testing window, expected request volume, credentials/identities used, and permitted techniques.

Do not use ERSEC to:

• access systems without authorization;
• obtain or exfiltrate private data;
• bypass access controls outside an approved test;
• deploy persistence or malware;
• damage systems or intentionally disrupt availability;
• harvest credentials or secrets from users.

The operator remains responsible for configuring scope and for validating that the selected identity, target, and scan profile are authorized.

---

Security and privacy considerations

ERSEC may process sensitive request/response evidence when scanning authenticated applications.

Treat generated reports and artifact directories accordingly. They may contain:

• endpoint paths;
• response metadata;
• snippets of application responses;
• security findings;
• authorization context;
• locally supplied configuration or identity-related evidence.

Store reports securely and avoid publishing raw reports when they contain sensitive application information.

Where possible, use redaction and evidence-minimization mechanisms before sharing reports outside the security team.

---

Troubleshooting

The browser engine is unavailable

ERSEC can use browser discovery when the local environment supports it. If the browser/Node runtime is not available, use static/API discovery or install the optional browser tooling required by your environment.

The scan is too slow

Review:

• --max-requests;
• --max-pages;
• concurrency/worker settings;
• profile selection;
• identity-workflow limits;
• context-probe limits.

Do not simply remove safety controls on a production target.

The application becomes rate-limited

Reduce request pressure and keep the configured rate limits. ERSEC's client includes bounded backoff behavior for common server-busy/rate-limiting responses.

A finding looks suspicious

Use the finding evidence and the re-verification workflow rather than assuming a detector signal equals a confirmed exploit.

---

Recommended assessment workflow

For a serious authorized assessment, a practical sequence is:

1. Establish scope

Define hosts, ports, paths, identities, request budgets, and testing windows.

2. Run passive/baseline discovery

Establish the application surface and obvious configuration problems first.

3. Run deeper behavioral analysis

Enable differential, API, authorization, workflow, and context-aware checks where appropriate.

4. Review attack paths and crown-jewel proximity

Prioritize issues that combine or reach high-value application surfaces.

5. Export evidence

Produce JSON/HTML/SARIF/Markdown and proof artifacts as needed.

6. Compile a security state

Persist the control-plane snapshot and security SLO representation.

7. Fix and re-verify

Use remediation artifacts, policy outputs, and exact-probe re-verification.

8. Repeat on the next build

Use cross-run drift/regression state to detect security changes rather than starting from zero.

---

Release philosophy

ERSEC 20 represents a shift from a conventional scanner toward an application-security control system.

The scanner remains important. It is the observation layer.

The larger system is:

Observe
  ↓
Model
  ↓
Question
  ↓
Differentiate
  ↓
Correlate
  ↓
Verify
  ↓
Prioritize
  ↓
Remediate
  ↓
Turn controls into policy
  ↓
Remember the previous state
  ↓
Detect regression

That is the direction of ERSEC: not "send more payloads," but build better evidence, better security context, better continuity, and better engineering feedback.

---

License

See the project distribution for licensing terms. Do not assume that third-party datasets, browser runtimes, local models, plugins, or external benchmark applications inherit the same license as ERSEC.

---

Final note

ERSEC is a security engineering tool, not a guarantee of security.

Use it as one layer in a broader program that includes secure design, code review, dependency management, identity architecture, threat modeling, manual testing, infrastructure security, incident readiness, and continuous remediation.

Its strongest use case is not a single dramatic scan result.

It is the ability to turn application behavior into a repeatable, evidence-backed security state that can be monitored, challenged, fixed, and compared over time.

---

Python package distribution

ERSEC is distributed on PyPI as a normal Python distribution. Build artifacts are produced from ersec.py using pyproject.toml:

python3 -m pip install --upgrade build twine
python3 -m build
python3 -m twine check dist/*

The Debian/Kali packaging tree lives under packaging/debian/ and is kept separate from Python package discovery.

For maintainers using GitHub Actions, the release workflow uses PyPI Trusted Publishing rather than storing a long-lived PyPI password in the repository. Configure the PyPI trusted publisher for the release.yml workflow and the pypi GitHub environment before publishing a release.