Normalize tool README top-of-file structure

tools/bofs/README.md

@@ -1,7 +1,13 @@
 # Reference BOFs
 
-Minimal Beacon Object Files demonstrating the bof-loader symbol allowlist.
-Each BOF uses only functions present in [`tools/rust/bof-loader/src/symbol_table.rs`](../rust/bof-loader/src/symbol_table.rs).
+Minimal Beacon Object Files demonstrating the bof-loader symbol allowlist. Each
+BOF uses only functions present in
+[`tools/rust/bof-loader/src/symbol_table.rs`](../rust/bof-loader/src/symbol_table.rs),
+confirming that safe post-exploitation tasks are achievable within the declared
+capability boundary.
+
+**Containment**: BOFs are executed by [`tools/rust/bof-loader/`](../rust/bof-loader/),
+which is ContainmentGuard-gated (`EXPLOIT_LAB_ACTIVE=1`).
 
 | BOF | Symbols used | Purpose |
 |-----|-------------|---------|

tools/browser-ext-attacks/README.md

@@ -1,9 +1,14 @@
 # Browser Extension Supply-Chain Attacks
 
-**Focus:** Manifest V3 capability analysis, lab malicious extension catalog,
-update-channel hijack simulation, and defender-side tooling.
+Manifest V3 capability analysis, lab malicious extension catalog, update-channel
+hijack simulation, and defender-side tooling. Each extension demonstrates a
+distinct capability retained by MV3 — cookie theft, form grabbing, traffic
+redirection, session interception — paired with Sigma detection rules.
 
----
+**Containment**: All extensions hard-check `LAB_MODE = true` and refuse to
+exfiltrate to anything other than `127.0.0.1`. All Python tools require
+`EXPLOIT_LAB_ACTIVE=1` and ContainmentGuard. These extensions are never
+submitted to the Chrome Web Store.
 
 ## Why Browser Extensions, Why Now
 
@@ -22,8 +27,6 @@ thousands of users within hours — silently, without any user action required.
 
 See [`docs/analysis/manifest-v3-capabilities.md`](../../docs/analysis/manifest-v3-capabilities.md) for the full technical analysis.
 
----
-
 ## Cyberhaven Incident (December 2024)
 
 The Cyberhaven Chrome extension (~400,000 users) was compromised:
@@ -37,8 +40,6 @@ The Cyberhaven Chrome extension (~400,000 users) was compromised:
 
 This repo's `update-hijack/` module simulates this pattern in a contained lab.
 
----
-
 ## Extension Catalog
 
 ### `cookie-theft/` — `chrome.cookies` API Exfil
@@ -112,8 +113,6 @@ End-to-end simulation of the Cyberhaven attack pattern:
 - `runtime_monitor.py` — CDP-based runtime monitoring of extension network
   activity and console output via Chrome remote debugging port
 
----
-
 ## Lab Architecture
 
 ```
@@ -129,8 +128,6 @@ Mock Web Store (update-hijack): 127.0.0.1:9800
 CDP Debug Port (eval):          127.0.0.1:9222
 ```
 
----
-
 ## Quick Start
 
 ### 1. Start the lab attacker server
@@ -166,8 +163,6 @@ python update-hijack/permission_differ.py \
   --after update-hijack/malicious_update/manifest.json
 ```
 
----
-
 ## Loading Extensions in Chrome / Chromium
 
 ```sh
@@ -188,21 +183,6 @@ Then:
 This ID is not registered with the Chrome Web Store. Do not submit these extensions
 to the Web Store.
 
----
-
-## Containment Summary
-
-All extensions enforce `LAB_MODE = true` in their JS source, which:
-- Requires `EXFIL_HOST` to be `127.0.0.1` or `localhost`
-- Aborts if the check fails
-
-All Python tools require `EXPLOIT_LAB_ACTIVE=1` and ContainmentGuard, which:
-- Enforces loopback-only network binding/connections
-- Refuses to run as root
-- Provides tmpdir isolation
-
----
-
 ## Documentation
 
 | Topic | Location |

tools/browser-ext-attacks/cookie-theft/README.md

@@ -1,9 +1,11 @@
 # Cookie Theft Demo Extension
 
-**Type:** Lab malicious extension — MV3 cookie theft via `chrome.cookies` API
-**Status:** Lab use only. NEVER publish to the Chrome Web Store.
+Lab Manifest V3 extension demonstrating cookie exfiltration via the `chrome.cookies`
+API. Shows that MV3 `chrome.cookies.getAll({})` with `<all_urls>` host permissions
+bypasses the HttpOnly restriction that protects session tokens from page-context JS.
 
----
+**Containment**: Lab use only — hard-checks `EXFIL_HOST` is `127.0.0.1` or `localhost`.
+Never publish to the Chrome Web Store.
 
 ## What This Demonstrates
 

tools/browser-ext-attacks/dnr-redirect/README.md

@@ -1,9 +1,12 @@
 # DNR Redirect Demo Extension
 
-**Type:** Lab malicious extension — DeclarativeNetRequest rule abuse
-**Status:** Lab use only. NEVER publish to the Chrome Web Store.
+Lab Manifest V3 extension demonstrating `declarativeNetRequest` abuse for silent
+traffic redirection. Static rules pass Chrome Web Store review; dynamic rules added
+via `updateDynamicRules()` are not re-reviewed, making post-deployment redirection
+target updates undetectable at submission time.
 
----
+**Containment**: Lab use only — redirects to `127.0.0.1` only. Never publish to
+the Chrome Web Store.
 
 ## What This Demonstrates
 

tools/browser-ext-attacks/eval/README.md

@@ -1,8 +1,12 @@
 # Eval — Defender-Side Extension Analysis Tools
 
-**Type:** Defensive tooling — static analysis and runtime monitoring
+Defender-side static analysis and runtime monitoring tooling for the extension lab.
+`manifest_analyzer.py` scores extension manifests for dangerous permission combinations;
+`runtime_monitor.py` uses the Chrome DevTools Protocol to monitor live extension
+network activity and console output.
 
----
+**Containment**: Read-only analysis tools. `runtime_monitor.py` requires a local
+Chromium instance with `--remote-debugging-port=9222`.
 
 ## Tools
 

tools/browser-ext-attacks/form-grab/README.md

@@ -1,9 +1,12 @@
 # Form Grab Demo Extension
 
-**Type:** Lab malicious extension — form credential grabbing via content script
-**Status:** Lab use only. NEVER publish to the Chrome Web Store.
+Lab Manifest V3 extension demonstrating credential harvesting via content script.
+MV3 content script restrictions are minimal — a script with `<all_urls>` and
+`all_frames: true` retains full DOM access and form event interception on every
+page, including SSO login iframes.
 
----
+**Containment**: Lab use only — exfiltrates to `127.0.0.1` only. Never publish to
+the Chrome Web Store.
 
 ## What This Demonstrates
 

tools/browser-ext-attacks/session-hijack/README.md

@@ -1,9 +1,12 @@
 # Session Hijack Demo Extension
 
-**Type:** Lab malicious extension — session token harvesting via `webRequest`
-**Status:** Lab use only. NEVER publish to the Chrome Web Store.
+Lab Manifest V3 extension demonstrating session token harvesting via
+`chrome.webRequest` observation. MV3 removed *blocking* webRequest but passive
+observation of all request and response headers — including `Authorization`,
+`Cookie`, and `Set-Cookie` — remains fully available.
 
----
+**Containment**: Lab use only — drains to `127.0.0.1` only. Never publish to
+the Chrome Web Store.
 
 ## What This Demonstrates
 

tools/browser-ext-attacks/update-hijack/README.md

@@ -1,9 +1,11 @@
 # Update Hijack Demo
 
-**Type:** Supply-chain simulation — publisher OAuth token compromise + silent update
-**Status:** Lab use only.
+End-to-end simulation of the Cyberhaven incident pattern: publisher OAuth token
+compromise, malicious update published to an existing extension ID, and Chrome's
+silent auto-update delivering it to all users — no exploit, no zero-day, just
+stolen developer credentials and an update channel with no re-review.
 
----
+**Containment**: Lab use only. Mock Web Store binds loopback only.
 
 ## What This Demonstrates
 

tools/browser-native-postex/README.md

@@ -1,9 +1,12 @@
-# browser-native-postex
+# Browser Native Post-Exploitation
 
 WASM-staged browser post-exploitation payload. Runs entirely inside the browser sandbox —
 no native process, no driver, no OS interaction. Uses WebAssembly compiled from Rust
 (wasm-bindgen) to perform post-exploitation through browser APIs: session storage,
-DOM, authenticated fetch channels.
+DOM, and authenticated fetch channels.
+
+**Containment**: The WASM module hard-checks `window.location.origin` and aborts if
+not in the lab allowlist (`127.0.0.1:850{1,2,3}`). Requires `EXPLOIT_LAB_ACTIVE=1`.
 
 ## Architecture
 

tools/byovd/README.md

@@ -1,7 +1,12 @@
 # BYOVD Orchestration Framework
 
 Python framework for BYOVD (Bring Your Own Vulnerable Driver) research.
-Provides a manifest-driven unified API over vulnerable kernel driver primitives.
+Provides a manifest-driven unified API over vulnerable kernel driver primitives,
+with hash-based blocklist checking and detection pairing for each covered driver.
+
+**Containment**: Requires `EXPLOIT_LAB_ACTIVE=1` and `EXPLOIT_LAB_OFFLINE_VM=1`.
+No actual driver files are committed — manifests reference hashes only.
+ContainmentGuard is enforced by `byovd_framework.py`.
 
 ## What It Does
 

tools/byovd/edr-killer-class/README.md

@@ -1,4 +1,4 @@
-# edr-killer-class
+# EDR Killer Class
 
 Research and detection content for BYOVD-based EDR termination tooling.
 

tools/byovd/loldrivers-integration/README.md

@@ -1,4 +1,4 @@
-# loldrivers-integration
+# LOLDrivers Integration
 
 Tools for fetching, analysing, and graphing the LOLDrivers catalog.
 

tools/c2/README.md

@@ -1,17 +1,13 @@
 # C2 Architecture Analysis
 
-> **DISCLAIMER:** Defensive security research material. The C2 server and beacon
-> operate on loopback-only networks, enforced by ContainmentGuard. The goal is to
-> help defenders understand and detect C2 patterns with real, capturable traffic.
-
----
-
-## Purpose
-
-Analyze Command and Control communication patterns documented in public
-threat intelligence (MITRE ATT&CK, Mandiant APT reports, Equation Group
-disclosures) and map them to modern browser-based threat scenarios. Each
-pattern is paired with detection guidance.
+Command and Control communication patterns drawn from public threat intelligence
+(MITRE ATT&CK, Mandiant APT reports, Equation Group disclosures), mapped to
+modern browser-based threat scenarios. Each pattern is paired with detection
+guidance so defenders can build rules against real, capturable traffic.
+
+**Containment**: The C2 server and beacon bind loopback only, enforced by
+ContainmentGuard. Requires `EXPLOIT_LAB_ACTIVE=1`. See
+[`tools/lib/containment.py`](../lib/containment.py).
 
 ## C2 Pattern Lineage
 

tools/dashboard/README.md

@@ -1,20 +1,13 @@
 # Session Management Dashboard
 
-> **Security Research Tool -- For authorized red-team, educational, and defensive use only.**
-> Unauthorized access to computer systems is illegal. This tool is provided to help defenders
-> understand adversary C2 management techniques and build better detections.
-
-## Purpose
-
 Centralized implant session management dashboard for browser exploit research.
-Models the management layer required to control large-scale implant deployments
-- the missing piece between initial exploitation and sustained access.
-
-The core problem: individual exploit sessions don't scale. Once an attacker
-has hundreds or thousands of compromised sessions, they need automation -
-group-based tasking, health monitoring, and audit trails. This dashboard
-demonstrates that capability gap and shows what detection opportunities
-it creates for defenders.
+Models the management layer that sits between initial exploitation and sustained
+access: group-based tasking, health monitoring, and audit trails across large
+numbers of implant sessions. Demonstrates the capability gap defenders need to
+address and the detection opportunities it creates.
+
+**Containment**: Requires `EXPLOIT_LAB_ACTIVE=1`. Connects only to the local
+C2 server ([`tools/c2/`](../c2/)) running on loopback.
 
 ## Components
 

tools/edr-silencing/README.md

@@ -1,12 +1,15 @@
 # EDR Silencing via Policy Abuse
 
-**Complement to:** [`tools/rust/telemetry-patch/`](../rust/telemetry-patch/) (memory patching)
+Policy and configuration layer attacks against EDR products — the attack surface
+that exists before any code executes or memory gets patched. Complements
+[`tools/rust/telemetry-patch/`](../rust/telemetry-patch/) (userland memory patching),
+which requires the policy layer to succeed first.
 
-## Overview
+**Containment**: Offensive tools require `EXPLOIT_LAB_ACTIVE=1` and
+`EXPLOIT_LAB_OFFLINE_VM=1`. Analysis tools (`edr_coverage_map.py`,
+`coverage_gap_advisor.py`) run without the offline VM gate.
 
-This directory covers the policy and configuration layer of EDR silencing —
-the attack surface that exists before any code executes or memory gets patched.
-Three distinct modules are provided:
+## Modules
 
 | Module | Path | Layer |
 |--------|------|-------|
@@ -100,12 +103,6 @@ to specific attacker capabilities.
 Key files: `edr_coverage_map.py`, `coverage_gap_advisor.py`,
 `edr_profiles/`, `detection/`
 
-## Containment Summary
-
-All offensive tools here require `EXPLOIT_LAB_OFFLINE_VM=1` and a Docker
-container (`ContainmentGuard.assert_offline_vm()`).  The analyzer and advisory
-tools run without the offline VM gate.
-
 ## Detection Summary
 
 | Event Source | Event IDs | Rules |

tools/edr-silencing/callback-integrity/README.md

@@ -1,9 +1,13 @@
-# callback-integrity
+# Callback Integrity
 
-Defender tools for kernel callback integrity monitoring.
+Defender tools for kernel callback integrity monitoring. Enumerates registered
+kernel callbacks, detects removals, and maps the coverage gaps that BYOVD
+callback-removal techniques exploit.
 
-**Scope: research + detection only.** No offensive callback removal code.
-See [`docs/analysis/kernel-callback-removal-research.md`](../../../docs/analysis/kernel-callback-removal-research.md) for the technique analysis.
+**Containment**: Research and detection only — no offensive callback removal code.
+Requires `EXPLOIT_LAB_ACTIVE=1` and `EXPLOIT_LAB_OFFLINE_VM=1`. See
+[`docs/analysis/kernel-callback-removal-research.md`](../../../docs/analysis/kernel-callback-removal-research.md)
+for the technique analysis.
 
 ## Tools
 

tools/entra-abuse/README.md

@@ -7,6 +7,10 @@ detection guidance. All tools run against a local mock IdP
 ([`infra/lab/mock-entra/`](../../infra/lab/mock-entra/)) — no real Microsoft
 services are contacted.
 
+**Containment**: Requires `EXPLOIT_LAB_ACTIVE=1` and `ENTRA_LAB_TENANT_ID` set to a lab
+tenant ID. ContainmentGuard rejects real tenant IDs at startup. See
+[`tools/lib/containment.py`](../lib/containment.py).
+
 ## What This Demonstrates
 
 | Tool | Technique | Real-World Impact |

tools/evasion/README.md

@@ -1,16 +1,13 @@
-# EDR Evasion Primitives — Detection-Paired Demonstrations
+# EDR Evasion Primitives
 
-**This directory contains detection-paired demonstrations, not deployable tooling.**
+Detection-paired demonstrations of core evasion primitives. Each subdirectory
+targets only toy code written for the purpose — a safe analog, not a
+deployable tool. Every demo ships with a `detection.md` giving the defender-side
+answer: what telemetry catches it, what the primitive cannot bypass, and concrete
+KQL/Sigma/Sysmon rules.
 
-Each subdirectory shows one evasion primitive as a safe analog — a self-contained
-experiment targeting only toy code we wrote. Every demo ships paired with a `detection.md`
-that gives the defender-side answer: what telemetry catches it, what it cannot bypass,
-and concrete KQL/Sigma/Sysmon rules.
-
-The goal is to understand *why* these primitives work so defenders can close the gap,
-not to provide a toolkit for attackers.
-
----
+**Containment**: Requires `EXPLOIT_LAB_ACTIVE=1`. Primitives target only toy binaries
+under `EXPLOIT_FIXTURE_ROOT`. No real processes or real drivers are manipulated.
 
 ## Demos