feat: modernize OpenGhost assessment workflow

Add local caching, stricter scope enforcement, evidence integrity, coverage tracking, modern assessment modules, improved reporting, and CI validation.

Author: VAIBHAVSING

.github/workflows/publish-sandbox-image.yml

@@ -86,5 +86,7 @@ jobs:
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          provenance: mode=max
+          sbom: true
           cache-from: type=gha
           cache-to: type=gha,mode=max

.github/workflows/validate.yml

@@ -0,0 +1,43 @@
+name: Validate skill
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate shell syntax
+        run: |
+          bash -n openghost
+          bash -n skills/openghost
+          bash -n skills/openghost-skill/openghost
+          bash -n skills/openghost-skill/scripts/openghost.sh
+          bash -n skills/openghost-skill/scripts/verify-toolchain.sh
+
+      - name: Validate Python syntax
+        run: |
+          python3 -m compileall -q skills/openghost-skill/scripts
+
+      - name: Validate skill references
+        run: |
+          python3 skills/openghost-skill/scripts/check-references.py
+
+      - name: Run deterministic helper tests
+        run: |
+          python3 -m unittest discover -s tests -v
+
+      - name: Reject generated engagement state
+        run: |
+          if git ls-files '.openghost/**' | grep -q .; then
+            echo 'Generated .openghost engagement state must not be committed.' >&2
+            exit 1
+          fi

.gitignore

@@ -3,3 +3,4 @@
 
 __pycache__/
 *.py[cod]
+.openghost/

AGENTS.md

@@ -74,6 +74,10 @@ Primary commands:
 ./openghost todo add ...
 ./openghost todo list
 ./openghost todo update ...
+./openghost coverage set ...
+./openghost context show
+./openghost evidence verify
+./openghost report validate
 ./openghost report generate
 ```
 
@@ -87,8 +91,11 @@ Compatibility aliases exist in `openghost.sh`; preserve them unless intentionall
 - `.openghost/current`
 - `.openghost/engagements/<name>/scope.yaml`
 - `.openghost/engagements/<name>/engagement.json`
-- `.openghost/engagements/<name>/findings.json`
-- `.openghost/engagements/<name>/todos.json`
+- `.openghost/engagements/<name>/state/findings.json`
+- `.openghost/engagements/<name>/state/evidence.json`
+- `.openghost/engagements/<name>/state/artifacts.json`
+- `.openghost/engagements/<name>/state/todos.json`
+- `.openghost/engagements/<name>/state/coverage.json`
 - evidence, notes, reports, artifacts, scripts, browser, and run directories.
 
 `OPENGHOST_SCOPE` should point to the active `scope.yaml` before testing. Scope files are operational data, not source docs.
@@ -143,7 +150,12 @@ bash -n skills/openghost-skill/scripts/verify-toolchain.sh
 For Python edits:
 
 ```bash
-python3 -m py_compile skills/openghost-skill/scripts/select-modules.py
+python3 -m py_compile skills/openghost-skill/scripts/select-modules.py \
+  skills/openghost-skill/scripts/scope_utils.py \
+  skills/openghost-skill/scripts/openghost-assess.py \
+  skills/openghost-skill/scripts/openghost-state.py
+python3 skills/openghost-skill/scripts/check-references.py
+python3 -m unittest discover -s tests -v
 ```
 
 For sandbox/runtime changes:

ARCHITECTURE.md

@@ -6,13 +6,17 @@ The agent owns planning, scope decisions, module selection, and reporting
 judgment. OpenGhost owns the sandboxed execution layer, deterministic helpers,
 engagement state, and evidence/report files.
 
+OpenGhost has no hosted control plane or managed service dependency. Runtime,
+state, caches, and credentials for authorized target applications stay local.
+
 ## Design Goals
 
 - Keep offensive tooling out of the host environment.
 - Make authorization, scope, and evidence explicit.
 - Give agents a short skill entrypoint with deeper references loaded only when
   relevant.
 - Keep engagement output separate from source code.
+- Reduce repeated agent context and deterministic work with local, invalidated caches.
 - Preserve one canonical launcher implementation.
 
 ## System Overview
@@ -91,16 +95,19 @@ Maintainers build the sandbox image from:
 docker/Dockerfile
 ```
 
-The sandbox mounts the current workspace at `/workspace`, starts from
-`WORKDIR /workspace`, and exposes tools only through the launcher allowlist.
+The sandbox mounts the current workspace read-only at `/workspace`, overlays
+`.openghost/` read-write for generated state, starts from `WORKDIR /workspace`,
+and exposes tools only through the launcher allowlist. Full workspace writes
+and the host gateway are explicit opt-ins. Memory, CPU, and process limits are
+set by the launcher.
 The launcher also contains a bash blocklist for obvious destructive host or
 system-damage patterns.
 
 ### State Helper
 
 `skills/openghost-skill/scripts/openghost-state.py` owns structured engagement
-state. The shell launcher delegates evidence, artifact, finding, todo, and
-report operations to this helper.
+state. The shell launcher delegates evidence, artifact, finding, todo,
+coverage, compact context, cache status, and report operations to this helper.
 
 Generated state normally lives under:
 
@@ -118,6 +125,7 @@ Generated state normally lives under:
         |-- scripts/
         |-- notes/
         |-- reports/
+        |-- cache/
         `-- runs/
 ```
 
@@ -156,6 +164,7 @@ assessment automation and parsing, not for bypassing scope or safety controls.
 openghost script run api-inventory -- --target-url https://target.example
   -> read manifest
   -> locate bundled script
+  -> reuse a content-addressed script/helper bundle
   -> execute inside Docker
 ```
 
@@ -167,12 +176,30 @@ directory.
 
 ```text
 openghost evidence add ...
+openghost evidence verify
 openghost finding add ...
+openghost coverage set ...
+openghost report validate
 openghost report generate
 ```
 
 Findings should reference evidence IDs and distinguish confirmed behavior from
-likely or possible signals.
+likely or possible signals. Evidence records include SHA-256 integrity metadata.
+Final report generation requires reviewed scope, closed coverage, valid evidence,
+complete confirmed findings, and no unresolved high-priority test work.
+
+### Local Cache Layers
+
+```text
+.openghost/cache/scripts/                         content-addressed script bundles
+.openghost/engagements/<name>/cache/assessment/ deterministic bounded outputs
+.openghost/engagements/<name>/cache/context/    compact agent resume snapshots
+```
+
+Cache keys include relevant source and state hashes. Target-authenticated
+assessment reuse is disabled by default. `openghost context show` is the
+preferred agent resume point so raw state and evidence are loaded only when
+needed for the active hypothesis.
 
 ## Trust Boundaries
 

DEVELOPMENT.md

@@ -38,7 +38,12 @@ Python changes:
 ```bash
 PYTHONPYCACHEPREFIX=/tmp/openghost-pycache python3 -m py_compile \
   skills/openghost-skill/scripts/select-modules.py \
-  skills/openghost-skill/scripts/openghost-state.py
+  skills/openghost-skill/scripts/scope_utils.py \
+  skills/openghost-skill/scripts/openghost-assess.py \
+  skills/openghost-skill/scripts/openghost-state.py \
+  skills/openghost-skill/scripts/check-references.py
+PYTHONPYCACHEPREFIX=/tmp/openghost-pycache python3 -m unittest discover -s tests -v
+python3 skills/openghost-skill/scripts/check-references.py
 rm -rf /tmp/openghost-pycache
 ```
 
@@ -108,7 +113,7 @@ OPENGHOST_BUILD=1 OPENGHOST_IMAGE=openghost-sandbox:dev ./openghost sandbox upda
 1. Add module guidance under `skills/openghost-skill/references/modules/`.
 2. Keep the module focused on one assessment area.
 3. Link it from `SKILL.md` only where agents need to discover it.
-4. Update `skills/openghost-skill/references/module-map.md` when module
+4. Update `skills/openghost-skill/references/modules/module-map.md` when module
    selection changes.
 5. Update `skills/openghost-skill/scripts/select-modules.py` when automatic
    selection should include the module.

README.md

@@ -12,6 +12,9 @@ plans the work, tests carefully, validates evidence, and writes findings.
 OpenGhost provides the Docker sandbox, scope files, evidence folders, reusable
 checks, and report templates.
 
+OpenGhost is fully local and open source. It has no hosted service, account,
+API key, telemetry requirement, or managed control plane.
+
 > [!IMPORTANT]
 > Use OpenGhost only on systems you are explicitly authorized to test.
 >
@@ -34,7 +37,7 @@ Use $openghost-skill to assess https://target.example.
 Authorization and scope details are in the engagement notes.
 ```
 
-Make sure Docker is running. Security tools are executed through the OpenGhost
+Make sure Docker is running and Bash 4.3+ plus Python 3 are available. Security tools are executed through the OpenGhost
 sandbox, not directly on your host machine.
 
 <details>
@@ -74,6 +77,8 @@ Create a scoped workspace before testing:
 openghost sandbox start
 openghost engagement init --url https://target.example --name target-example
 export OPENGHOST_SCOPE=.openghost/engagements/target-example/scope.yaml
+# Edit scope.yaml, set authorization.reviewed: true, then validate it.
+openghost scope validate
 ```
 
 Edit the generated scope file:
@@ -140,7 +145,7 @@ openghost script run api-inventory -- --target-url https://target.example
 Record evidence:
 
 ```bash
-openghost evidence add --path response.txt --kind response --title "Baseline response"
+openghost evidence add --path response.txt --kind response --title "Baseline response" --redaction redacted
 ```
 
 Save a confirmed finding:
@@ -163,6 +168,10 @@ openghost finding add \
 Generate the report:
 
 ```bash
+openghost context show
+openghost coverage set --module server-integrity --status tested
+openghost evidence verify
+openghost report validate
 openghost report generate
 ```
 
@@ -201,9 +210,12 @@ openghost browser devtools --url https://target.example --zap
 
 ```bash
 openghost todo add --task "Complete surface mapping" --module surface-map --priority high
-openghost evidence add --path <file> --kind <kind> --title <title>
+openghost evidence add --path <file> --kind <kind> --title <title> --redaction <raw|redacted|sanitized>
 openghost artifact add --path <file> --kind <kind> --title <title>
 openghost finding add --title <title> --severity <severity> --module <module> --url <url> --confidence <90-100> --evidence E-001
+openghost coverage set --module <module> --status <status>
+openghost evidence verify
+openghost report validate
 openghost report generate
 ```