ZAP provider actor: typed API control, scope, scan jobs, and alerts #21

New issue

Open

opened 2026-08-25 07:36:57 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-08-25 07:36:57 +00:00

(Migrated from github.com)

Goal

Promote OWASP ZAP from a Nyxt proxy toggle into a supervised Hackmode provider with typed commands/results.

The current Nyxt zap-mode only forwards a buffer through localhost:8080. Keep proxy routing as a client concern; put reusable ZAP API semantics here.

Provider boundary

Implement a ZAP adapter/provider actor using the official ZAP REST API with configurable endpoint and API key loaded from a secret reference/environment, never source control.

Initial operations:

version/health/status
contexts and explicit in-scope URLs/regexes
sites/URLs discovered by ZAP
passive-scan queue/status
alerts + alert summaries
traditional spider start/status/stop
active-scan start/status/stop only through an explicit scoped operation

Represent long work as Hackmode jobs with IDs/status/cancellation rather than blocking calls.

Safety / scope invariant

Active scanning is never inferred from the current browser URL alone.

Before an active scan can start:

a Hackmode operation must be selected;
target must be explicitly present in that operation's authorized scan scope;
the ZAP context must resolve to the same allowed scope;
the caller must explicitly request active scan;
inScopeOnly/context restriction must be used where supported.

No Internet-wide fan-out or implicit expansion to sibling hosts.

Typed outputs

Normalize ZAP data into provider result types first. Then emit canonical Hackmode assets/findings through existing protocols, preserving:

URL
alert/rule/plugin ID
risk/confidence
parameter/evidence where safe
description/solution/reference metadata
scan/context ID
observed timestamp
raw provider payload reference
provenance = OWASP ZAP

Reliability

deadlines and bounded concurrency
classified transport/API errors
provider restart/failure isolation
dedupe repeated alerts by stable provider identity + target
never log API keys

Tests

Use a fake ZAP transport for deterministic tests plus an optional local ZAP integration fixture.

Required proofs:

API key redaction
passive alert retrieval
spider lifecycle
active scan rejected when target is outside operation scope
repeated alert import dedupes
cancellation does not kill unrelated provider work

References

Official ZAP API supports REST control for spider, passive/active scanning and alert retrieval; action endpoints require an API key in normal secured setups.

## Goal Promote OWASP ZAP from a Nyxt proxy toggle into a supervised Hackmode provider with typed commands/results. The current Nyxt `zap-mode` only forwards a buffer through `localhost:8080`. Keep proxy routing as a client concern; put reusable ZAP API semantics here. ## Provider boundary Implement a ZAP adapter/provider actor using the official ZAP REST API with configurable endpoint and API key loaded from a secret reference/environment, never source control. Initial operations: - version/health/status - contexts and explicit in-scope URLs/regexes - sites/URLs discovered by ZAP - passive-scan queue/status - alerts + alert summaries - traditional spider start/status/stop - active-scan start/status/stop only through an explicit scoped operation Represent long work as Hackmode jobs with IDs/status/cancellation rather than blocking calls. ## Safety / scope invariant Active scanning is never inferred from the current browser URL alone. Before an active scan can start: 1. a Hackmode operation must be selected; 2. target must be explicitly present in that operation's authorized scan scope; 3. the ZAP context must resolve to the same allowed scope; 4. the caller must explicitly request active scan; 5. `inScopeOnly`/context restriction must be used where supported. No Internet-wide fan-out or implicit expansion to sibling hosts. ## Typed outputs Normalize ZAP data into provider result types first. Then emit canonical Hackmode assets/findings through existing protocols, preserving: - URL - alert/rule/plugin ID - risk/confidence - parameter/evidence where safe - description/solution/reference metadata - scan/context ID - observed timestamp - raw provider payload reference - provenance = OWASP ZAP ## Reliability - deadlines and bounded concurrency - classified transport/API errors - provider restart/failure isolation - dedupe repeated alerts by stable provider identity + target - never log API keys ## Tests Use a fake ZAP transport for deterministic tests plus an optional local ZAP integration fixture. Required proofs: - API key redaction - passive alert retrieval - spider lifecycle - active scan rejected when target is outside operation scope - repeated alert import dedupes - cancellation does not kill unrelated provider work ## References Official ZAP API supports REST control for spider, passive/active scanning and alert retrieval; action endpoints require an API key in normal secured setups.

nsaspy referenced this issue

2026-09-02 17:24:36 +00:00

Chain OWASP ZAP through canonical mitmproxy/IPX capture and correlate alerts #33

nsaspy referenced this issue

2026-09-02 17:24:36 +00:00

Default HTTP capture + browser-profile egress for spawned providers #38

nsaspy commented

2026-09-02 17:24:42 +00:00

Owner

Architecture update from operator direction / #133: retain the ZAP provider for ZAP-native API semantics (health, contexts, passive alerts, spider and explicitly scoped active-scan jobs), but do not make ZAP a second raw HTTP capture authority. Configure ZAP outbound/upstream traffic through the operation-scoped mitmproxy/IPX service where supported, then link ZAP-specific alerts/findings back to canonical HTTP exchange evidence when correlation is available.

This keeps ZAP control useful while avoiding duplicate proxy-history persistence.