Discover. Validate. Prove.
Container-native security assessment and validation platform with controlled execution and evidence-backed findings.
Current release: v0.6.0 — Phase 5 Intelligence
Quick Start · Current Capabilities · Architecture · Security · Roadmap · Contributing
RedDock explores how security tooling can become portable, container-native, policy-controlled, reproducible, and evidence-driven instead of a collection of host-specific scripts. It is designed for authorized environments and intentionally grows through small, verified phases.
Its operating model is simple: AI proposes. Policy authorizes. Tools execute. Evidence proves. An explicit authorized scope and DockGuard control every target, non-invasive discovery produces hashed evidence, deterministic detectors turn observations into traceable findings, and validation is limited to an approval-gated recheck of a narrow class of HTTP finding. Optional intelligence can send one reviewed, evidence-linked packet to an operator-configured model for structured advice; it has no tools and cannot act. There is no exploitation, credential attack, or payload of any kind.
| Capability | Current implementation |
|---|---|
| Runtime | One Dockerized application that serves the UI and API on the same origin |
| Workspaces | Dockyards that own an explicit authorized scope |
| Scope policy | DockGuard evaluates every target deterministically and fails closed |
| Discovery | Nmap host and TCP service discovery, plus a single-request HTTP origin probe |
| Inventory | Normalized assets and services that reconcile across repeat discovery |
| Observations | Dated, adapter-attributed records of what was seen — never findings |
| Detection | Deterministic detectors that read stored observations and reach nothing |
| Findings | Normalized conclusions with separate severity and confidence, deduplicated by fingerprint |
| Lifecycle | Findings resolve rather than disappear, and operator decisions survive later runs |
| Validation | A separately approved, fixed HTTP-origin recheck for eligible open header findings |
| Correlation | Evidence-linked asset/finding relationships and fixed CWE classifications |
| RedPath | A graph where every edge explains its basis and names its supporting SHA-256 evidence |
| Intelligence | Optional, approval-gated model advice over an exact packet the operator reviews first |
| CVE enrichment | A boundary with an optional local catalogue; an association, never a verdict |
| Evidence | SHA-256-hashed run artifacts, including validation packages and intelligence input/output provenance |
| Persistence | SQLite and evidence stored in a named Docker volume |
| Safety | Non-invasive profiles only; no scripting, brute force, evasion, or exploitation |
Findings: severity and confidence stated separately, with the detector, the observation, and the SHA-256 that supports each one.
The dashboard: workspace metrics and the discovery audit trail, including a run DockGuard denied.
The Dockyard workspace: a target must pass DockGuard before discovery can be launched.
Detection: the registered detectors, what each of them reads, and what a completed run produced.
Docker Engine or Docker Desktop with Docker Compose is the supported way to run RedDock. Nmap ships inside the image; nothing is installed on your host.
git clone https://github.com/chriswayneh/RedDock.git
cd RedDock
docker compose up --buildOpen http://localhost:8080. The health endpoint is http://localhost:8080/api/health, and interactive API documentation is at http://localhost:8080/docs.
Stop the application with docker compose down. The reddock-data volume holds both the database and retained evidence and survives normal container recreation; use docker compose down -v only when you deliberately want to erase local data.
Intelligence is off by default. To enable it, provide an OpenAI-compatible API base URL and model to the container. For a model server running on the Docker host, a Compose override can pass values already present in your shell:
services:
reddock:
environment:
REDDOCK_LLM_BASE_URL: ${REDDOCK_LLM_BASE_URL}
REDDOCK_LLM_MODEL: ${REDDOCK_LLM_MODEL}
REDDOCK_LLM_API_KEY: ${REDDOCK_LLM_API_KEY:-}For example, a compatible local endpoint might use
REDDOCK_LLM_BASE_URL=http://host.docker.internal:11434/v1. Any endpoint that
uses REDDOCK_LLM_API_KEY, including a local one, must use HTTPS; cloud
endpoints must use HTTPS and usually require that key. Keep credentials in
your shell or secret manager; do not add them to Compose files or commit them.
The provider receives nothing until you create a packet, inspect its exact JSON
and destination in the UI, and submit a separate approval note.
- Create a Dockyard to represent an authorized engagement workspace.
- Define its authorized scope: included targets, and exclusions that always win.
- Enter a target and ask DockGuard for a decision. It answers
ALLOWEDor a specific denial with the reason and the scope entry that decided it. - Run a safe discovery profile. The server re-evaluates DockGuard immediately before the adapter is invoked, so an out-of-scope target is never reached.
- Results normalize into assets, services, and observations, and the run's raw output, normalized result, and metadata are retained and hashed.
- Run detection. It contacts nothing: every registered detector reads what the Dockyard already recorded and returns findings, each naming the rule that produced it and the observations it was drawn from.
- For an eligible open HTTP security-header finding, request validation. This records intent only. Add an approval note to recheck DockGuard immediately before RedDock sends its fixed, bodyless HTTP probe; the raw response summary, normalized conclusion, metadata, and manifest are retained as a hash-linked evidence package.
- Run correlation. RedDock reads only stored assets, findings, observations, and hashes, then renders an explainable RedPath graph and fixed CWE classifications without contacting a target.
- Optionally create an intelligence packet from the latest correlation. RedDock stores and hashes the exact JSON without contacting a provider. Review it and the destination, then add a separate approval note to request structured remediation and prioritization advice.
Run the same discovery again and RedDock updates what it already knows rather than duplicating it, while every observation is kept as history. Run detection again and the same issue stays one finding whose last_seen moves, while an issue that is no longer reproduced is marked resolved rather than quietly removed.
flowchart TB
Browser[Browser] --> UI[React UI]
UI --> API[FastAPI API]
API --> Guard{DockGuard}
Guard -->|denied| Audit[Recorded denial]
Guard -->|allowed| Adapter[Discovery adapter]
Adapter --> Normalize[Assets · Services · Observations]
Normalize --> Database[(SQLite named Docker volume)]
Adapter --> Evidence[(Hashed evidence)]
API --> Detect[Detector]
Database --> Detect
Detect --> Findings[Findings]
Findings --> Database
Findings -.cites.-> Evidence
Database --> Correlate[Correlation]
Correlate --> RedPath[RedPath graph]
RedPath -.cites.-> Evidence
Database --> Packet[Intelligence review packet]
Packet --> Approval2[Local approval note]
Approval2 --> Model[Configured model provider]
Model --> Advice[Structured advice only]
Packet --> Evidence
Advice --> Evidence
Findings --> Request[Validation request]
Request --> Approval[Local approval note]
Approval --> Guard
Guard -->|allowed| Recheck[Fixed HTTP origin recheck]
Recheck --> Evidence
Discovery and the tightly bounded validation recheck are the only paths that touch a target, and both pass DockGuard immediately before contact. Detection and correlation read only stored state. Intelligence may contact only the configured model provider after the operator reviews the exact retained packet and records a separate approval. It receives no target or tool capability. A validation or intelligence request alone makes no network contact.
The production image builds the React application and serves it from the same FastAPI process that exposes /api. There is deliberately no reverse proxy, separate frontend service, queue, or remote dependency; discovery runs on a small bounded thread pool inside the application and detection runs inline. See ARCHITECTURE.md for the scope model, the adapter and detector boundaries, and the trust boundaries.
AI proposes. Policy authorizes. Tools execute. Evidence proves.
- Scope is explicit and server-enforced. DockGuard evaluates every target twice — when the run is requested and again immediately before the tool is invoked. The UI cannot bypass it.
- Denials are specific.
denied_out_of_scope,denied_excluded,invalid_target, andunresolvedeach carry the reason and the matching scope entry. - Fail closed. Anything DockGuard cannot positively place inside the authorized scope is denied, including a scope it cannot parse.
- Names and addresses stay separate. A hostname is never authorized because it resolves into an authorized network, and there is no wildcard or subdomain expansion.
- Tools never receive operator flags. Argument vectors are generated internally from a fixed table of safe options, executed without a shell, bounded by timeouts, and built only from targets normalized to a character set that cannot form an option.
- Dangerously broad scope is rejected. A scope entry may not cover more than 256 addresses, and a default route is never valid.
- Observations are not findings. An observation records what an adapter saw and carries no severity or verdict. A finding is a separate thing: a normalized conclusion one named detector drew, which cannot exist without the observations it cites.
- Detectors reach nothing. A detector is handed an immutable snapshot and no session, socket, subprocess, target, or operator option. A test parses the detection package and fails the build if that stops being true.
- A finding is checkable. It names the detector and rule that produced it, the observations behind it, the runs involved, and the SHA-256 of the retained artifact.
- Validation is deliberately smaller than a scanner. It applies only to eligible open HTTP header findings, targets their recorded origin, accepts no URL, payload, credential, cookie, command, or option, follows no redirect, reads no body, and requires a separate approval note. DockGuard is re-evaluated immediately before its single fixed probe.
- Ratings are not inflated. Severity and confidence are separate fields, missing hardening headers are
low, and there is no risk score, CVSS vector, or aggregate rating, because RedDock does not compute one. - CVE data is never invented. RedDock downloads none. Enrichment is optional, local, exact-match only, and never changes a severity or a status.
- Correlation asserts only what evidence supports. Exact stored identifiers produce relationships; every RedPath edge explains its basis and carries its evidence hash. No edge claims reachability, exploitability, causation, or risk.
- Intelligence is a reviewable disclosure, not an agent. It is disabled by default. The operator sees the exact evidence-linked packet and configured destination before separately approving transmission. The model gets no tools, targets, credentials, commands, or state-changing API, and its structured references must already exist in the packet.
Read SECURITY.md for the authorized-use policy and the full control list.
backend/ FastAPI API, DockGuard, adapters, detectors, intelligence, evidence, and SQLite
frontend/ React and TypeScript dashboard
scripts/ Local end-to-end smoke test
docs/ Architecture decisions and project documentation
.github/ Continuous-integration workflow
| Document | Purpose |
|---|---|
| Architecture | Current system boundaries and future design seams |
| Security | Authorized-use policy and product safety model |
| Roadmap | Phased delivery plan and clear separation of planned work |
| Contributing | Local checks and contribution guidelines |
| Changelog | Release history |
v0.6.0 delivers Phase 5 — Intelligence: opt-in local or cloud OpenAI-compatible advice, exact packet review before disclosure, separate approval, provider and prompt-version binding, strict output validation, and hashed input/output provenance. The model receives no tools and cannot change RedDock state.
v0.5.0 delivers Phase 4 — Correlation: stored-state-only correlation snapshots, exact-address asset relationships, evidence-linked finding correlations, fixed CWE mappings, and the RedPath graph.
v0.4.0 delivered Phase 3 — Validation: an approval-gated, scope-rechecked, non-destructive HTTP-origin recheck for eligible open security-header findings, with confirmed, not_reproduced, or indeterminate outcomes, separate confidence, and a hashed raw/normalized/metadata/manifest evidence package.
v0.3.0 delivered Phase 2 — Detection: the detector contract and registry, detection runs, normalized findings with separate severity and confidence, deduplication by stable fingerprint, a lifecycle that resolves rather than deletes, evidence links from every finding back to the observations and hashes behind it, and the CVE enrichment boundary.
v0.2.1 finalized Phase 1 with consistent version metadata across the application, API, and packages.
v0.2.0 delivered Phase 1 — Discovery: DockGuard scope enforcement, asset/service/observation models, the Nmap and HTTP discovery adapters, discovery-run auditing, and the RedLedger evidence foundation.
v0.1.0 delivered Phase 0 — Foundation: a containerized React/FastAPI application, local Dockyard persistence, a dashboard, documentation, tests, and CI.
Next after v0.6.0: Phase 6 — Reporting. Technical and executive reports, evidence manifests, and portable DockPack exports remain planned. See the roadmap for the complete phased plan.
Contributions are welcome when they preserve the safety model and keep changes small and tested. Start with CONTRIBUTING.md, and report potential vulnerabilities through SECURITY.md or GitHub Private Vulnerability Reporting.
RedDock is human-directed and intentionally uses a mixed-AI engineering workflow. Claude Code and OpenAI Codex have both contributed implementation and review work; repository source, tests, security controls, and owner review—not model output—remain the authority for what ships.
MIT.
Python · FastAPI · Pydantic · SQLAlchemy · SQLite · Nmap · React · TypeScript · Vite · Docker · GitHub Actions
Discover. Validate. Prove.
Controlled security validation, built one verified phase at a time.