fix: repo-wide security hardening from ZAP, Scorecard, and CodeQL audit (#357)

Aureliolo · web-flow · commit 27eb28840ecf · 2026-03-13T22:02:49.000+01:00
## Summary Repo-wide security hardening based on audit findings from ZAP DAST, OSSF Scorecard, and CodeQL alerts. - **ZAP fixes**: Add `NotFoundException` → 404 handler (prevents 500 on unmatched routes), add `Cross-Origin-Resource-Policy` and `Cache-Control` response headers, add `HTTPException` catch-all handler preserving correct status codes (405, 429, etc.) - **Scorecard fixes**: Pin sandbox Dockerfile images by SHA-256 digest, add `--ignore-scripts` to wrangler CI install, add Dependabot coverage for `docker/sandbox` - **Exception handler hardening**: Static error messages for 401/403 (prevent `exc.detail` leakage), wire `API_ROUTE_NOT_FOUND` event constant for structured logging, add MRO resolution comment - **Documentation**: New comprehensive `docs/security.md` page, landing page Security section with clickable cards, library reference search exclusion, README Security link, scoped `check-yaml --unsafe` to `mkdocs.yml` only - **CodeQL**: Dismissed 3 false-positive alerts via GitHub API (#10, #22, #23) - **Branch protection**: Updated protect-main ruleset with required status checks (`ci-pass`) and PR reviews Closes #356 ## Test plan - [x] `uv run ruff check src/ tests/` — all checks passed - [x] `uv run mypy src/ tests/` — no issues in 917 files - [x] `uv run pytest tests/ -n auto --cov=ai_company --cov-fail-under=80` — 7465 passed, 94.69% coverage - [x] New tests: `test_unmatched_route_returns_404`, `test_method_not_allowed_maps_to_405`, `test_litestar_permission_denied_maps_to_403`, `test_litestar_not_authorized_maps_to_401`, `test_litestar_validation_exception_maps_to_400`, `test_security_response_headers[Strict-Transport-Security]` - [x] Astro landing page builds successfully - [x] Web dashboard: lint (0 errors), type-check, tests (453 passed) ## Review coverage Pre-reviewed by 7 specialized agents (code-reviewer, python-reviewer, pr-test-analyzer, silent-failure-hunter, logging-audit, security-reviewer, docs-consistency). 10 findings implemented across all severity levels.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -62,3 +62,17 @@ updates:
       - Aureliolo
     labels:
       - type:chore
+
+  - package-ecosystem: docker
+    directory: /docker/sandbox
+    schedule:
+      interval: daily
+      time: "06:00"
+      timezone: Etc/UTC
+    commit-message:
+      prefix: "chore"
+    open-pull-requests-limit: 5
+    reviewers:
+      - Aureliolo
+    labels:
+      - type:chore
diff --git a/.github/workflows/dast.yml b/.github/workflows/dast.yml
@@ -19,7 +19,10 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      issues: write  # Required by API scan action to create issues for scan findings
+      # The ZAP action creates/updates a single GitHub issue per repo with scan
+      # findings (not one per run). Removing issues:write would cause the action
+      # to fail. The auto-created issue is updated in-place on subsequent runs.
+      issues: write
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
diff --git a/.github/workflows/pages-preview.yml b/.github/workflows/pages-preview.yml
@@ -233,7 +233,9 @@ jobs:
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           PR_NUMBER: ${{ needs.build.outputs.pr_number }}
         run: |
-          npm i --no-save wrangler@3.114.17
+          # Scorecard: npm install cannot be hash-pinned for CI-only tools;
+          # --ignore-scripts mitigates post-install script supply-chain risk.
+          npm i --no-save --ignore-scripts wrangler@3.114.17
           npx wrangler pages deploy _site --project-name=synthorg-pr-preview --branch="pr-${PR_NUMBER}"
 
       - name: Comment preview URL
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -14,7 +14,11 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
-        exclude: ^src/ai_company/templates/builtins/
+        exclude: ^(src/ai_company/templates/builtins/|mkdocs\.yml$)
+      - id: check-yaml
+        name: check-yaml (mkdocs, unsafe for !!python tags)
+        args: [--unsafe]
+        files: ^mkdocs\.yml$
       - id: check-toml
       - id: check-json
       - id: check-merge-conflict
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -60,6 +60,7 @@ npm --prefix web run test                  # Vitest unit tests
 - **Design spec**: `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations)
 - **Architecture**: `docs/architecture/` (overview, tech-stack, decision log)
 - **Roadmap**: `docs/roadmap/` (status, open questions, future vision)
+- **Security**: `docs/security.md` (comprehensive security architecture, hardening, CI/CD security, compliance)
 - **Reference**: `docs/reference/` (research, standards)
 - **REST API reference**: `docs/rest-api.md` — links to standalone Scalar UI page at `docs/_generated/api-reference.html` (both generated by `scripts/export_openapi.py` in CI)
 - **Library reference**: `docs/api/` — auto-generated from docstrings via mkdocstrings + Griffe (AST-based, no imports)
@@ -150,7 +151,7 @@ web/              # Vue 3 + PrimeVue + Tailwind CSS dashboard
 - **Every module** with business logic MUST have: `from ai_company.observability import get_logger` then `logger = get_logger(__name__)`
 - **Never** use `import logging` / `logging.getLogger()` / `print()` in application code
 - **Variable name**: always `logger` (not `_logger`, not `log`)
-- **Event names**: always use constants from the domain-specific module under `ai_company.observability.events` (e.g. `PROVIDER_CALL_START` from `events.provider`, `BUDGET_RECORD_ADDED` from `events.budget`, `CFO_ANOMALY_DETECTED` from `events.cfo`, `CONFLICT_DETECTED` from `events.conflict`, `MEETING_STARTED` from `events.meeting`, `CLASSIFICATION_START` from `events.classification`, `CONSOLIDATION_START` from `events.consolidation`, `ORG_MEMORY_QUERY_START` from `events.org_memory`, `API_REQUEST_STARTED` from `events.api`, `CODE_RUNNER_EXECUTE_START` from `events.code_runner`, `DOCKER_EXECUTE_START` from `events.docker`, `MCP_INVOKE_START` from `events.mcp`, `SECURITY_EVALUATE_START` from `events.security`, `HR_HIRING_REQUEST_CREATED` from `events.hr`, `PERF_METRIC_RECORDED` from `events.performance`, `TRUST_EVALUATE_START` from `events.trust`, `PROMOTION_EVALUATE_START` from `events.promotion`, `PROMPT_BUILD_START` from `events.prompt`, `MEMORY_RETRIEVAL_START` from `events.memory`, `MEMORY_BACKEND_CONNECTED` from `events.memory`, `MEMORY_ENTRY_STORED` from `events.memory`, `MEMORY_BACKEND_SYSTEM_ERROR` from `events.memory`, `AUTONOMY_ACTION_AUTO_APPROVED` from `events.autonomy`, `TIMEOUT_POLICY_EVALUATED` from `events.timeout`, `PERSISTENCE_AUDIT_ENTRY_SAVED` from `events.persistence`, `TASK_ENGINE_STARTED` from `events.task_engine`, `COORDINATION_STARTED` from `events.coordination`, `COMMUNICATION_DISPATCH_START` from `events.communication`, `COMPANY_STARTED` from `events.company`, `CONFIG_LOADED` from `events.config`, `CORRELATION_ID_CREATED` from `events.correlation`, `DECOMPOSITION_STARTED` from `events.decomposition`, `DELEGATION_STARTED` from `events.delegation`, `EXECUTION_LOOP_STARTED` from `events.execution`, `GIT_OPERATION_START` from `events.git`, `PARALLEL_EXECUTION_STARTED` from `events.parallel`, `PERSONALITY_LOADED` from `events.personality`, `QUOTA_CHECKED` from `events.quota`, `ROLE_ASSIGNED` from `events.role`, `ROUTING_STARTED` from `events.routing`, `SANDBOX_EXECUTE_START` from `events.sandbox`, `TASK_CREATED` from `events.task`, `TASK_ASSIGNMENT_STARTED` from `events.task_assignment`, `TASK_ROUTING_STARTED` from `events.task_routing`, `TEMPLATE_LOADED` from `events.template`, `TOOL_INVOKE_START` from `events.tool`, `WORKSPACE_CREATED` from `events.workspace`). Import directly: `from ai_company.observability.events.<domain> import EVENT_CONSTANT`
+- **Event names**: always use constants from the domain-specific module under `ai_company.observability.events` (e.g. `PROVIDER_CALL_START` from `events.provider`, `BUDGET_RECORD_ADDED` from `events.budget`, `CFO_ANOMALY_DETECTED` from `events.cfo`, `CONFLICT_DETECTED` from `events.conflict`, `MEETING_STARTED` from `events.meeting`, `CLASSIFICATION_START` from `events.classification`, `CONSOLIDATION_START` from `events.consolidation`, `ORG_MEMORY_QUERY_START` from `events.org_memory`, `API_REQUEST_STARTED` from `events.api`, `API_ROUTE_NOT_FOUND` from `events.api`, `CODE_RUNNER_EXECUTE_START` from `events.code_runner`, `DOCKER_EXECUTE_START` from `events.docker`, `MCP_INVOKE_START` from `events.mcp`, `SECURITY_EVALUATE_START` from `events.security`, `HR_HIRING_REQUEST_CREATED` from `events.hr`, `PERF_METRIC_RECORDED` from `events.performance`, `TRUST_EVALUATE_START` from `events.trust`, `PROMOTION_EVALUATE_START` from `events.promotion`, `PROMPT_BUILD_START` from `events.prompt`, `MEMORY_RETRIEVAL_START` from `events.memory`, `MEMORY_BACKEND_CONNECTED` from `events.memory`, `MEMORY_ENTRY_STORED` from `events.memory`, `MEMORY_BACKEND_SYSTEM_ERROR` from `events.memory`, `AUTONOMY_ACTION_AUTO_APPROVED` from `events.autonomy`, `TIMEOUT_POLICY_EVALUATED` from `events.timeout`, `PERSISTENCE_AUDIT_ENTRY_SAVED` from `events.persistence`, `TASK_ENGINE_STARTED` from `events.task_engine`, `COORDINATION_STARTED` from `events.coordination`, `COMMUNICATION_DISPATCH_START` from `events.communication`, `COMPANY_STARTED` from `events.company`, `CONFIG_LOADED` from `events.config`, `CORRELATION_ID_CREATED` from `events.correlation`, `DECOMPOSITION_STARTED` from `events.decomposition`, `DELEGATION_STARTED` from `events.delegation`, `EXECUTION_LOOP_STARTED` from `events.execution`, `GIT_OPERATION_START` from `events.git`, `PARALLEL_EXECUTION_STARTED` from `events.parallel`, `PERSONALITY_LOADED` from `events.personality`, `QUOTA_CHECKED` from `events.quota`, `ROLE_ASSIGNED` from `events.role`, `ROUTING_STARTED` from `events.routing`, `SANDBOX_EXECUTE_START` from `events.sandbox`, `TASK_CREATED` from `events.task`, `TASK_ASSIGNMENT_STARTED` from `events.task_assignment`, `TASK_ROUTING_STARTED` from `events.task_routing`, `TEMPLATE_LOADED` from `events.template`, `TOOL_INVOKE_START` from `events.tool`, `WORKSPACE_CREATED` from `events.workspace`). Import directly: `from ai_company.observability.events.<domain> import EVENT_CONSTANT`
 - **Structured kwargs**: always `logger.info(EVENT, key=value)` — never `logger.info("msg %s", val)`
 - **All error paths** must log at WARNING or ERROR with context before raising
 - **All state transitions** must log at INFO
diff --git a/README.md b/README.md
@@ -121,6 +121,7 @@ graph TB
 | [Architecture](docs/architecture/index.md) | System overview, tech stack, decision log |
 | [API Reference](docs/rest-api.md) | REST API reference (Scalar/OpenAPI) |
 | [Library Reference](docs/api/index.md) | Auto-generated from docstrings |
+| [Security](docs/security.md) | Security architecture, hardening, CI/CD security |
 | [Developer Setup](docs/getting_started.md) | Clone, test, lint, contribute |
 | [User Guide](docs/user_guide.md) | Install, configure, run via Docker |
 
diff --git a/docker/sandbox/Dockerfile b/docker/sandbox/Dockerfile
@@ -1,6 +1,6 @@
-FROM node:22-slim AS node-base
+FROM node:22-slim@sha256:9c2c405e3ff9b9afb2873232d24bb06367d649aa3e6259cbe314da59578e81e9 AS node-base
 
-FROM python:3.14-slim
+FROM python:3.14.3-slim@sha256:6a27522252aef8432841f224d9baaa6e9fce07b07584154fa0b9a96603af7456
 
 COPY --from=node-base /usr/local/bin/node /usr/local/bin/node
 COPY --from=node-base /usr/local/lib/node_modules /usr/local/lib/node_modules
diff --git a/docs/api/api.md b/docs/api/api.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # API Layer
 
 Litestar REST + WebSocket API — controllers, authentication, guards, and channels.
diff --git a/docs/api/budget.md b/docs/api/budget.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Budget
 
 Cost tracking, budget enforcement, auto-downgrade, quota management, and CFO optimization.
diff --git a/docs/api/communication.md b/docs/api/communication.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Communication
 
 Inter-agent messaging — bus, dispatcher, delegation, loop prevention, conflict resolution, and meeting protocols.
diff --git a/docs/api/config.md b/docs/api/config.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Config
 
 YAML company configuration loading and validation.
diff --git a/docs/api/core.md b/docs/api/core.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Core
 
 Shared domain models, base types, and enums used across the framework.
diff --git a/docs/api/engine.md b/docs/api/engine.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Engine
 
 Agent orchestration, execution loops, task decomposition, routing, and parallel execution.
diff --git a/docs/api/hr.md b/docs/api/hr.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # HR
 
 Agent lifecycle management — hiring, firing, onboarding, offboarding, performance tracking, and promotion/demotion.
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Library Reference
 
 Auto-generated reference documentation from source code docstrings.
diff --git a/docs/api/memory.md b/docs/api/memory.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Memory
 
 Persistent agent memory — protocol, retrieval pipeline, shared org memory, consolidation, and archival.
diff --git a/docs/api/observability.md b/docs/api/observability.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Observability
 
 Structured logging, event constants, correlation tracking, and log sinks.
diff --git a/docs/api/persistence.md b/docs/api/persistence.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Persistence
 
 Pluggable operational data persistence — protocol, configuration, and SQLite backend.
diff --git a/docs/api/providers.md b/docs/api/providers.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Providers
 
 LLM provider abstraction — protocol, base class, drivers, capabilities, routing, and resilience.
diff --git a/docs/api/security.md b/docs/api/security.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Security
 
 Security subsystem — rule engine, trust strategies, autonomy levels, output scanning, and timeout policies.
diff --git a/docs/api/templates.md b/docs/api/templates.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Templates
 
 Pre-built company templates, personality presets, and template builder.
diff --git a/docs/api/tools.md b/docs/api/tools.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 # Tools
 
 Tool system — base class, registry, invoker, built-in tools, and MCP bridge.
diff --git a/docs/security.md b/docs/security.md
diff --git a/mkdocs.yml b/mkdocs.yml
diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro
diff --git a/src/ai_company/api/app.py b/src/ai_company/api/app.py
diff --git a/src/ai_company/api/exception_handlers.py b/src/ai_company/api/exception_handlers.py
diff --git a/src/ai_company/observability/events/api.py b/src/ai_company/observability/events/api.py
diff --git a/tests/unit/api/test_app.py b/tests/unit/api/test_app.py
diff --git a/tests/unit/api/test_exception_handlers.py b/tests/unit/api/test_exception_handlers.py
