Find. Validate. Prove.
RedDock is an open-source vulnerability discovery, validation, and evidence platform for authorized environments. It combines scoped scanning, explainable findings, evidence-backed validation, and portable reports.
Current release: v0.8.1, Phase 8 Production hardening checkpoint
Start Here · What It Checks · Screenshots · Security · Documentation · Roadmap
RedDock can perform host discovery, scan Nmap's top 100 TCP ports with light version detection, or make one bodyless HTTP-origin probe. Its built-in rules review selected HTTP security headers, TLS certificate verification results, and identified Telnet or FTP services. A separately gated lab profile expands one host to Nmap's top 1,000 TCP ports.
Today's release does not yet test UDP, credentials, exploitability, response bodies, NSE scripts, brute force, payloads, or evasion, and it ships no CVE feed. Those are development targets, not permanent product limits:
- v1.1.0: locally cached CVE, CISA KEV, and EPSS intelligence.
- v1.2.0: bounded UDP discovery, sanitized HTTP response sampling, and reviewed non-intrusive service checks.
- v1.3.0: least-privilege credentialed checks with strict secret isolation.
- v1.4.0: evidence-based exploitability validation for supported findings.
- v2.0.0: a separately installed commercial pack for authorized credential auditing, exploit validation, controlled payloads, and evasion exercises.
The complete versioned roadmap explains the security and completion gates for each release. A catalogue match will remain an association rather than proof that a service is affected; stronger claims require target evidence and a supported validation result.
- Local only. The supported Compose package publishes one host-loopback port. Do not expose it to a LAN, public tunnel, proxy, or the internet.
- No user login. The local package uses an operator token to protect changes, but that token is an accident boundary, not identity, SSO, or shared-user access.
- Not a certification. Findings describe what narrow checks observed and concluded. A clean result does not prove a target is secure.
- AI has no tools. AI is optional and receives only a packet the operator reviews and approves. It cannot scan, change findings, or apply remediation.
| Question | RedDock's answer |
|---|---|
| What did it check? | Authorized scope, completed discovery runs, and retained observations show which focused checks ran. |
| What did it find? | Rule-based findings keep severity separate from confidence and link back to what was observed. |
| What supports the result? | SHA-256-hashed evidence and named detector rules provide a traceable record. |
| What can I save or share? | Technical and plain-language reports, plus an unencrypted DockPack containing verified supporting files. |
Each finding explains the conclusion, its severity and confidence, and the evidence behind it.
For an authorized local evaluation, start from the immutable reviewed tag:
git clone --branch v0.8.1 --depth 1 https://github.com/chriswayneh/RedDock.git
cd RedDock
docker compose up --buildOpen http://localhost:8080. On the first start, copy the generated operator token from docker compose logs reddock, enter it in the browser, and select Unlock changes. The master token stays in the reddock-data volume; the browser receives only a short-lived local session. If the token file is removed after initialization, RedDock refuses changes instead of silently replacing it.
See the step-by-step first-run guide for the local demonstration, shutdown instructions, and troubleshooting. Contributors can use master, which may contain unfinished work newer than the stable tag.
I want one transparent platform that helps find vulnerabilities and keeps the scope, conclusion, and supporting evidence together. These questions guide how I build it:
- Can it expand vulnerability coverage without losing control of authorized scope?
- Can a finding keep a clear trail back to the evidence behind it?
- Can it distinguish a possible association from an observed and validated weakness?
- Can optional AI help explain results without receiving tools or control?
- Can the project be honest about unfinished work instead of hiding it?
I keep the source, tests, architecture notes, and tradeoffs visible so anyone interested can see how the project evolves. Passing automated checks is useful evidence, not a security certification.
RedDock treats browser input, target output, model output, stored paths, and archives as untrusted. DockGuard checks scope immediately before target contact, tools receive fixed arguments without a shell, and stored-data features receive no target capability. The Compose application listens on a Unix socket shared only with its loopback ingress proxy; optional Ollama and PostgreSQL services do not receive that socket. Containers run with bounded resources, read-only root filesystems where supported, dropped capabilities, and no-new-privileges.
Local access does not authorize a target: the configured engagement scope and applicable approval gates still decide whether an operation may proceed. The operator, host, Docker daemon, and deployment configuration remain trusted. The operator token is not a multi-user identity system.
These are concrete zero-trust controls, not a complete enterprise zero-trust architecture or a claim that RedDock is ready for shared or internet-facing use. See the security model and threat model.
Expand the implementation details
| Capability | Current implementation |
|---|---|
| Runtime | One Dockerized application that serves the UI and API on the same origin |
| API explorer | Optional OpenAPI schema and Swagger UI, disabled by default |
| 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 explicit state changes without guessing about unscanned ports |
| Observations | Dated, adapter-attributed records of what was seen. Observations are not 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 |
| Local AI | Qwen3.5 4B through Ollama is the recommended default; any compatible provider remains configurable |
| Reporting | Deterministic technical and executive reports over one bounded retained snapshot, including lab-policy history |
| DockPack | Portable ZIP export with a member manifest and verified source evidence |
| CVE enrichment | A boundary with an optional local catalogue; an association, never a verdict |
| Evidence | SHA-256-hashed run artifacts, validation packages, intelligence provenance, and reporting manifests |
| Persistence | SQLite by default or PostgreSQL 17 on an internal backend network; evidence retained in a named Docker volume |
| Safety | Non-invasive profiles only; no scripting, brute force, evasion, or exploitation |
| Lab controls | Deployment opt-in plus a separate, short-lived per-Dockyard authorization and audit ledger |
| Extensions | Data-only detector manifests with strict schema checks and content-addressed provenance |
First run starts empty and keeps changes locked until the local operator token is entered.
Open a finding's detail view to see its explanation and supporting evidence.
See how results connect. Click a relationship to inspect its supporting evidence. A connection is not proof of an exploitable attack path.
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.
Hand off your work: generate an executive summary, a technical report, and a downloadable package of supporting evidence.
Manifest view: the evidence manifest is readable and clickable in the app, while the original raw JSON remains available for machine verification.
Know what is running: inspect your version and deployment gates without exposing credentials.
API explorer: the built-in Swagger UI is available when the local developer flag is enabled.
Phase 7 lab policy: deployment opt-in, temporary per-Dockyard authorization, fixed capability bounds, immediate revocation, and the audit ledger in one view.
Detector provenance: reviewed built-ins and a data-only organization rule publish their source, passive execution model, content-addressed version, and manifest hash.
New to command-line tools? Use the step-by-step first-run guide, including the current development-build warning, operator unlock, local demo, plain-English glossary, and troubleshooting.
Process liveness is at http://localhost:8080/api/health, and database-backed readiness is at http://localhost:8080/api/ready. Swagger and the OpenAPI download are disabled by default. Developers can enable the local API explorer.
Stop the application with docker compose down. In the default profile, the reddock-data volume holds the SQLite database, retained evidence, and local operator token. It survives normal container recreation. Use docker compose down -v only when you deliberately want to erase local data.
Protect that volume with the offline SQLite backup, verification, restore, and recovery procedure. Backups contain sensitive assessment evidence and are not encrypted.
Use Compose, and do not publish port 8080 beyond loopback. The ingress proxy binds
127.0.0.1:8080, and only that proxy receives the application's Unix socket. The local operator token protects changes but is not user authentication and does not protect safe reads. Publishing the raw image or proxy, sharing the socket volume, or attaching another service to the ingress boundary is not supported.
RedDock ships in two supported Compose shapes:
| Package | Command | Model behavior |
|---|---|---|
| Core | docker compose up --build |
No LLM runtime or weights; every non-intelligence feature works and Intelligence reports that it is disabled |
| Local AI bundle | docker compose -f compose.yaml -f compose.ollama.yaml up --build |
Builds the fixed rootless Ollama wrapper on an internal backend network and downloads Qwen3.5 4B into a named local volume on first use |
The core/no-LLM package remains the secure default because running discovery,
detection, validation, correlation, reporting, and DockPack export never
requires a model. The optional bundle packages the runtime and provisioning
workflow, not 3.4 GB of model weights inside the RedDock image or Git history.
It is not exposed on a host port. Set REDDOCK_LLM_MODEL to another Ollama model
before startup, or configure any compatible local or cloud provider instead.
The rootless bundle uses a new reddock-ollama-v2 volume, so its first start
downloads the selected model again. An older root-owned cache is left untouched;
remove that old volume only after you identify it and decide it is no longer needed.
Only loopback addresses and the internal ollama service are classified as local
model destinations. host.docker.internal crosses into the host, is classified
as external, and therefore requires HTTPS.
See Local and configurable AI for provider overrides,
data-boundary rules, storage, first-run behavior, and the approval flow.
On systems with Make, make up and make up-ai are equivalent shortcuts.
Place a strong password in the ignored file runtime/secrets/reddock-postgres-password, then run:
docker compose -f compose.yaml -f compose.postgres.yaml up --buildThis keeps the ingress proxy on 127.0.0.1:8080, adds a pinned PostgreSQL 17
service on an internal backend network with no host port, and mounts the password into both containers as a
Compose secret. It validates the database path for Phase 8; it does not enable
the future authenticated server mode. The PostgreSQL and Ollama overlays can be
combined. See Optional PostgreSQL for safe password entry,
storage, shutdown, and external-orchestrator settings.
Lab capabilities require both a deployment-owner switch and a short-lived per-Dockyard authorization; the API cannot enable the deployment switch. See Lab mode. Organization-specific detector policy can be installed only as bounded, data-only JSON manifests, never as executable plugin code. See Detector plugins.
- 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.
- Generate a report snapshot. RedDock re-verifies retained evidence, renders technical and executive reports, builds a manifest, and packages the exact source artifacts into a reproducible DockPack without contacting a target or model.
- In an isolated authorized lab, optionally enable the deployment gate and create a short-lived Dockyard grant before using the fixed extended service-discovery profile. Every authorization and decision remains in the lab audit ledger.
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 or PostgreSQL)]
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
Database --> Report[Deterministic report snapshot]
Evidence --> Report
Report --> DockPack[Reports · manifest · source 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, correlation, and reporting 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, and reporting never does.
The production image builds the React application and serves it from the same FastAPI process that exposes /api. In Compose, that process listens only on a Unix socket. A small unprivileged ingress proxy owns the host-loopback TCP port and is the only service given the socket. Optional PostgreSQL and Ollama services use separate internal backend networks and receive no API socket. Discovery runs on a small bounded thread pool inside the application and detection runs inline. See ARCHITECTURE.md for the scope model, adapter and detector boundaries, and trust boundaries.
- Scope is explicit. DockGuard checks every target when a run is requested and again immediately before contact. Anything it cannot place inside the allowed scope is denied.
- Checks stay narrow. RedDock builds fixed tool arguments internally, uses no shell, rejects dangerously broad scope, and places time limits on active work.
- Evidence and conclusions stay separate. Observations record what a check saw. Findings explain what a named rule concluded and must link back to supporting observations and hashes.
- Stored-data features cannot reach targets. Detection, correlation, and reporting receive no target or network capability. Optional AI receives only a reviewed packet and has no tools or state-changing access.
- Rechecks require a separate decision. Validation is limited to eligible HTTP-header findings, requires approval, and passes DockGuard again before its fixed probe.
- Claims stay conservative. RedDock keeps severity separate from confidence, does not treat a CVE association as proof, and does not calculate an aggregate risk score.
- Exports verify their inputs. Reports and DockPacks include only bounded, database-referenced files whose retained hashes still match.
Read SECURITY.md for the authorized-use policy and the full control list.
backend/ FastAPI API, DockGuard, adapters, detectors, intelligence, reporting, evidence, and SQL persistence
frontend/ React and TypeScript dashboard
scripts/ Local end-to-end smoke test
docs/ Architecture decisions and project documentation
.github/ Continuous-integration workflow
| Document | Purpose |
|---|---|
| Start here | Install, try a local assessment, understand the results, and stop without losing data |
| Documentation guide | Choose a reading path for trying, operating, or developing RedDock |
| Architecture | Current system boundaries and future design seams |
| Security | Authorized-use policy and product safety model |
| Threat model | Current trust boundaries, attacker stories, and Phase 8 security objectives |
| Roadmap | Phased delivery plan and clear separation of planned work |
| Local AI | Recommended Ollama model and compatible-provider configuration |
| PostgreSQL | Internal Compose backend, secret handling, and current deployment boundary |
| SQLite backup and restore | Offline verified backups, rollback-safe restore, and interrupted-restore recovery |
| Lab mode | Independent gates, fixed capability, and audit behaviour |
| Detector plugins | Data-only extension schema, install path, limits, and trust model |
| Contributing | Local checks and contribution guidelines |
| Changelog | Release history |
| DockPack format | Portable report and evidence package layout and verification |
| Nmap corresponding source | Locate the exact Nmap source archives carried in security-updated images |
The current release is v0.8.1, Phase 8 Production hardening checkpoint. Its local workflow covers scoped discovery through reports and DockPack exports, plus separately gated lab controls, data-only detector extensions, and the hardened local boundary described above. See the changelog for release-by-release history.
Phase 8 remains in development. Current work tightens the local operator boundary, separates API ingress from optional sidecars, caps resource use, and improves first-run clarity. Dormant identity, session, OIDC, and tenant foundations remain disabled. There is no sign-in route, no supported server mode, and no shared-user deployment. See the roadmap for technical checkpoints and remaining gates.
RedDock is MIT-licensed and owner-directed. Bug reports and design discussion are welcome. Please read CONTRIBUTING.md before starting implementation work. Report potential vulnerabilities through SECURITY.md or GitHub Private Vulnerability Reporting, not a public issue.
I use Claude Code and OpenAI Codex for implementation and review assistance. The repository source, tests, documented controls, and my review determine what ships. Contribution attribution details live in CONTRIBUTING.md.
Licensed under the MIT License. Use it, fork it, modify it, or build something of your own. See LICENSE for the terms.
If this project helped you, a ⭐ is appreciated.
Python · FastAPI · Pydantic · SQLAlchemy · SQLite · PostgreSQL · Nmap · React · TypeScript · Vite · Docker · GitHub Actions
Discover. Validate. Prove.
Controlled security validation, built one verified phase at a time.