feat: formalize security contracts and stabilize benchmark gate (#3)

Author: ErenAri

.github/workflows/benchmark.yml

@@ -30,6 +30,9 @@ jobs:
       - name: Run benchmarks
         run: |
           ./build-bench/aegisbpf_bench \
+            --benchmark_min_time=0.2 \
+            --benchmark_repetitions=8 \
+            --benchmark_report_aggregates_only=true \
             --benchmark_format=json \
             --benchmark_out=benchmark.json \
             --benchmark_out_format=json
@@ -43,8 +46,21 @@ jobs:
             echo "exists=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Store benchmark result
-        if: steps.benchmark-history.outputs.exists == 'true'
+      - name: Store benchmark result (PR advisory)
+        if: steps.benchmark-history.outputs.exists == 'true' && github.event_name == 'pull_request'
+        uses: benchmark-action/github-action-benchmark@v1
+        with:
+          tool: googlecpp
+          output-file-path: benchmark.json
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          auto-push: false
+          alert-threshold: '150%'
+          fail-on-alert: false
+          comment-on-alert: false
+          summary-always: true
+
+      - name: Store benchmark result (main strict)
+        if: steps.benchmark-history.outputs.exists == 'true' && github.event_name != 'pull_request'
         uses: benchmark-action/github-action-benchmark@v1
         with:
           tool: googlecpp

README.md

@@ -488,6 +488,9 @@ sudo aegisbpf run --enforce --seccomp
 
 See [SECURITY.md](SECURITY.md) for vulnerability reporting, environment variables, and hardening details.
 
+Security boundaries, attacker model, and known blind spots are documented in
+[docs/THREAT_MODEL.md](docs/THREAT_MODEL.md).
+
 ## Documentation
 
 ### Core Documentation
@@ -498,7 +501,9 @@ See [SECURITY.md](SECURITY.md) for vulnerability reporting, environment variable
 | [API_REFERENCE.md](docs/API_REFERENCE.md) | API reference for types, functions, and BPF maps |
 | [DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) | Development setup, coding standards, and contribution guide |
 | [POLICY.md](docs/POLICY.md) | Policy file format and semantics |
+| [POLICY_SEMANTICS.md](docs/POLICY_SEMANTICS.md) | Precise runtime rule semantics and edge-case behavior |
 | [NETWORK_LAYER_DESIGN.md](docs/NETWORK_LAYER_DESIGN.md) | Network blocking architecture |
+| [THREAT_MODEL.md](docs/THREAT_MODEL.md) | Threat model, coverage boundaries, and known bypass surface |
 
 ### Operations
 
@@ -510,6 +515,7 @@ See [SECURITY.md](SECURITY.md) for vulnerability reporting, environment variable
 | [RELEASE_DRILL.md](docs/RELEASE_DRILL.md) | Pre-release packaging and upgrade drill |
 | [KEY_MANAGEMENT.md](docs/KEY_MANAGEMENT.md) | Policy signing key rotation and revocation runbook |
 | [INCIDENT_RESPONSE.md](docs/INCIDENT_RESPONSE.md) | Incident handling procedures |
+| [METRICS_OPERATIONS.md](docs/METRICS_OPERATIONS.md) | Metric interpretation, thresholds, and operator actions |
 | [runbooks/](docs/runbooks/) | Alert/incident/maintenance operational runbooks |
 | [VENDORED_DEPENDENCIES.md](docs/VENDORED_DEPENDENCIES.md) | Vendored dependency inventory and review cadence |
 | [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common issues and solutions |

SECURITY.md

@@ -20,6 +20,18 @@ not include exploit details.
 
 Initial triage target: acknowledgement within 48 hours.
 
+## Threat Model and Security Boundaries
+
+Authoritative security scope is documented in `docs/THREAT_MODEL.md`.
+
+At a high level:
+- **In scope:** unprivileged process/container attempts to perform denied
+  file/network operations.
+- **Out of scope:** host root compromise, malicious kernel modules, and
+  physical/firmware attacks.
+- **Important boundary:** if BPF LSM is unavailable, AegisBPF degrades to
+  audit-only behavior and cannot enforce file denial.
+
 
 ## Security Hardening
 
@@ -164,3 +176,8 @@ The following environment variables affect security behavior. In production, avo
 1. **BPF LSM requirement**: Full blocking requires BPF LSM to be enabled in the kernel.
 2. **Root namespace only**: The agent must run in the host PID/cgroup namespace.
 3. **No live policy reload**: Policy changes require agent restart.
+4. **Namespace/path ambiguity**: Path canonicalization occurs in the agent mount
+   namespace; bind-mount and overlay paths can differ from workload-visible
+   paths.
+5. **Coverage limits**: Network enforcement currently focuses on connect/bind
+   hooks; other socket paths are not yet covered.

config/required_checks.txt

@@ -1,20 +1,20 @@
-Benchmark / benchmark
-CI / build (ubuntu-22.04)
-CI / build (ubuntu-24.04)
-CI / clang-tidy
-CI / coverage
-CI / lint
-CI / label-contract
-CI / required-checks-contract
-CI / sanitizers (asan)
-CI / sanitizers (tsan)
-CI / sanitizers (ubsan)
-CI / sbom
-CI / smoke-fuzz
-CI / test
-Security / dependency-review
-Security / codeql
-Security / gitleaks
-Security / semgrep
-Release Readiness / readiness (ubuntu-22.04)
-Release Readiness / readiness (ubuntu-24.04)
+benchmark
+build (ubuntu-22.04)
+build (ubuntu-24.04)
+clang-tidy
+coverage
+lint
+label-contract
+required-checks-contract
+sanitizers (asan)
+sanitizers (tsan)
+sanitizers (ubsan)
+sbom
+smoke-fuzz
+test
+dependency-review
+codeql
+gitleaks
+semgrep
+readiness (ubuntu-22.04)
+readiness (ubuntu-24.04)

config/required_checks_release.txt

@@ -1,21 +1,21 @@
-Benchmark / benchmark
-CI / build (ubuntu-22.04)
-CI / build (ubuntu-24.04)
-CI / clang-tidy
-CI / coverage
-CI / lint
-CI / label-contract
-CI / required-checks-contract
-CI / sanitizers (asan)
-CI / sanitizers (tsan)
-CI / sanitizers (ubsan)
-CI / sbom
-CI / smoke-fuzz
-CI / test
-Release Branch Guard / guard
-Release Readiness / readiness (ubuntu-22.04)
-Release Readiness / readiness (ubuntu-24.04)
-Security / dependency-review
-Security / codeql
-Security / gitleaks
-Security / semgrep
+benchmark
+build (ubuntu-22.04)
+build (ubuntu-24.04)
+clang-tidy
+coverage
+lint
+label-contract
+required-checks-contract
+sanitizers (asan)
+sanitizers (tsan)
+sanitizers (ubsan)
+sbom
+smoke-fuzz
+test
+guard
+readiness (ubuntu-22.04)
+readiness (ubuntu-24.04)
+dependency-review
+codeql
+gitleaks
+semgrep

docs/API_REFERENCE.md

@@ -849,5 +849,7 @@ inline constexpr uint32_t kLayoutVersion = 1;
 
 - [ARCHITECTURE.md](ARCHITECTURE.md) - System design overview
 - [POLICY.md](POLICY.md) - Policy file format details
+- [POLICY_SEMANTICS.md](POLICY_SEMANTICS.md) - Runtime semantics and edge cases
+- [THREAT_MODEL.md](THREAT_MODEL.md) - Security boundaries and blind spots
 - [NETWORK_LAYER_DESIGN.md](NETWORK_LAYER_DESIGN.md) - Network blocking design
 - [KEY_MANAGEMENT.md](KEY_MANAGEMENT.md) - Key rotation procedures

docs/BRANCH_PROTECTION.md

@@ -26,6 +26,9 @@ in sync by `.github/workflows/label-sync.yml`.
 
 Use `config/required_checks.txt` as the source of truth.
 
+Check names are stored as **job names** (for example, `build (ubuntu-24.04)`
+or `semgrep`) to match GitHub branch-protection contexts directly.
+
 For protected `release/*` branches, use `config/required_checks_release.txt`.
 
 ## Audit command

docs/COMPATIBILITY.md

@@ -76,6 +76,20 @@ AegisBPF cannot run if:
 
 \* Requires adding `lsm=bpf` or `lsm=landlock,lockdown,yama,bpf` to kernel boot parameters.
 
+## Distribution and Runtime Quirks
+
+- **Ubuntu 22.04 (5.15)**: stable baseline for LSM hooks; ensure BTF package is present on custom kernels.
+- **Ubuntu 24.04 (6.5+)**: newer libbpf/kernel combos are generally smoother for CO-RE.
+- **RHEL 9.x (5.14)**: verify backported BPF features; some behavior differs from upstream 5.14 docs.
+- **Container hosts**: run the agent in host PID/cgroup/mount namespaces for deterministic cgroup and path behavior.
+- **Kubernetes**: privileged pods (or pods with host-level capabilities) are outside normal workload threat assumptions.
+
+## Filesystem and Namespace Notes
+
+- Path canonicalization is performed in the agent namespace at policy-apply time.
+- Bind mounts and overlay filesystems can present alternative path views for the same inode.
+- Inode-based rules remain the primary enforcement primitive; path-only expectations can diverge in namespaced setups.
+
 ## Enabling BPF LSM
 
 ### Method 1: GRUB (Recommended)

docs/DEVELOPER_GUIDE.md

@@ -739,5 +739,7 @@ git push origin v0.2.0
 
 - [API_REFERENCE.md](API_REFERENCE.md) - API documentation
 - [ARCHITECTURE.md](ARCHITECTURE.md) - System design
+- [THREAT_MODEL.md](THREAT_MODEL.md) - Security scope and blind spots
+- [POLICY_SEMANTICS.md](POLICY_SEMANTICS.md) - Runtime policy behavior
 - [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues
 - [VENDORED_DEPENDENCIES.md](VENDORED_DEPENDENCIES.md) - Vendored dependency tracking

docs/KEY_MANAGEMENT.md

@@ -3,6 +3,13 @@
 This runbook defines how to rotate and revoke policy-signing keys used by
 AegisBPF signed policy bundles.
 
+## Strategy
+
+- Keep private keys outside hosts (KMS/HSM or offline signer).
+- Trust only root-owned public keys on hosts.
+- Enforce monotonic `policy_version` to block rollback bundles.
+- Treat key add/remove operations as security-change events with two-person review.
+
 ## Model
 
 - Trusted public keys are loaded from `/etc/aegisbpf/keys` (or