Skip to content

Sync - #1

Merged
vtobi merged 83 commits into
f5devcentral:mainfrom
henleda:main
Oct 2, 2026
Merged

vtobi merged 83 commits into
f5devcentral:mainfrom
henleda:main

Conversation

@vtobi

@vtobi vtobi commented Oct 2, 2026

Copy link
Copy Markdown
Collaborator

Proposed changes

Describe the use case and detail of the change. If this PR addresses an issue on GitHub, make sure to include a link to that issue using one of the supported keywords in this PR's description or commit message.

Checklist

Before creating a PR, run through this checklist and mark each as complete:

henleda and others added 30 commits August 5, 2026 21:46
…hing

The old doc predated roughly half the product. It had no Simulate step, no CVE
/ manifest / OpenAPI inputs, no declarative-WAF emit, no BIG-IP lab, no audit
sink, no CWE/OWASP mapping, no benchmark and no MCP — and it described two
paths when there are now three meaningfully different levels of proof.

Rewritten as a GUI walkthrough:

  A — offline, no cloud and no keys, from the curated dataset
  B — live on F5 XC: a real exploit blocked at a real edge
  C — the declarative WAF: the same policy emitted for BIG-IP AS3 and NGINX
      App Protect, answering "we are not an F5 shop"

Each says up front what it needs and what it proves, with a note to pick one
and finish it rather than run half of each.

Adds a "when something declines mid-demo" table. Every decline in this tool is
a deliberate answer — no band-aid fits, MITRE prohibits the obvious CWE, the
replay could not be measured, the cure has not merged — and in front of a
security audience those are the most credible moments available. The table
gives the line to say for each.

FIXTURE FIX, found while verifying the doc rather than writing it from memory:
the curated summary has always claimed "9 candidates, 6 verified, 2 refuted, 1
dropped" while shipping only the 6 verified findings. So the report could not
render its "Candidates the verify agent did not confirm" section at all — the
demo advertised a funnel it was structurally unable to show, and the dataset
contradicted its own metrics.

demo/build_demo_out.py now ships the three non-verified candidates in
findings.json but NOT in triage.json, which is exactly how a real run
represents them. They are realistic false positives of the kind verify actually
catches: an eval() sink that is not reachable, a "hardcoded password" that is a
test fixture, and a missing rate limit that already exists upstream. The report
now renders "3 of 9 candidates", the severity and OWASP charts still count 6,
and the console's Review table still shows 6 rows.

Verified by running Demo A end to end in a browser, not from memory: the
console renders the CWE badges (`CWE-89 · mapped`), the chip row reads
9/6/5/6, the OWASP chart carries its `(no category)` bar, and the refuted
section appears below the fold.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs(demo): rewrite DEMO.md as a console-driven walkthrough of everything
Adds infra/vpcopilot-lab/ — the copilot's own validation lab as Terraform,
adapted from nimbus-demo/infra for the new AWS account. Fixes the "no IaC in
the repo" gap so the estate is codified and travels to the new laptop.

- Advanced-WAF BIG-IP VE (AMI auto-resolved from F5's Marketplace owner, or
  pinned), 2-NIC, public VIP EIP, management reachable ONLY via an SSM tunnel.
- Larkspur origin (t3.small, Docker) behind the appliance, fixed 10.30.10.22
  so `vpcopilot bigip-lab create` examples copy-paste.
- Dedicated VPC 10.30.0.0/16, deliberately separate from nimbus-demo.
- onboard/bigip-onboard.sh scripts the two documented traps: poll mcp-state
  before provisioning asm:nominal, then curl-install AS3.
- Makefile cost controls (lab-up / lab-down / lab-nuke), tag-scoped to
  Project=vpcopilot-lab so a stop can never touch another estate.
- No load generators; no credentials or state in the tree (see .gitignore).

terraform validate passes; plan = 20 to add against account 113938649684.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
infra: Terraform module for the vpcopilot-lab (AWAF BIG-IP + Larkspur)
…scription

`make check` counted visible AWAF images and printed "(subscription OK)", but F5's
AWAF AMIs are public — every account sees them regardless of entitlement. That gave
a false green; the real apply then failed with OptInRequired. Reword the check to
say visibility is not subscription, and document that the real test is a dry-run
launch (or apply), with the product URL from the error. README also notes pinning
`bigip_ami` to the subscribed image so a retry can't drift to another SKU.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…n RE-IP list

The external SG only admitted 443 from the VPC, so with xc_re_cidrs empty the kept
XC tenant's Regional Edges could not reach the origin at all. Add allow_public_vip
(default true) to open 443 to 0.0.0.0/0 — F5's own recommendation over maintaining
a Regional-Edge IP allowlist (the ranges change without notice). Lock the origin at
L7 with a header check on the appliance if a private origin is needed; xc_re_cidrs
remains an optional escape hatch.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
wait_mcpd split `show sys mcp-state field-fmt` on a colon, but that output is
space-separated ("    phase running"), so it always read "unknown" and would burn
the full 90x10s timeout even though mcpd was up. Match the phase line directly.

Also fall back to resolving the AS3 rpm asset URL from the GitHub releases API if
the pinned f5-appsvcs-<ver>-4.noarch.rpm name 404s (the build suffix moves).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…oll task status

The AS3 install POSTed packageFilePath=/var/tmp/..., which iControl LX rejects
instantly (FAILED in ~0.2s) — it only installs RPMs staged under
/var/config/rest/downloads. Download there instead. Also poll the
package-management task to FINISHED/FAILED (surfacing the error) rather than only
watching /shared/appsvcs/info, which stays empty on a failed install and masked it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The copilot's `bigip-lab create` builds a clean-slate HTTP VIP on port 80 (no TLS —
WAF policy attaches at L7), but the external SG opened 443, so the dataplane was
unreachable (VIP returned 000 while the origin was 200). Open port 80 for the
public/VPC/XC/admin rules. Description left unchanged (immutable → would force an SG
replacement); the port-80 reality is documented in a comment instead.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
infra(vpcopilot-lab): port-80 VIP, allow_public_vip, onboard + subscription fixes
Apply the official F5-FY26 brand kit (from the FY26 PowerPoint theme) to
the ops console:

- header on F5 black with the F5 logo (served via a new /f5-logo.png
  route) and an F5-red underline; hero band gains an F5-red rail
- palette swapped off navy/indigo to F5 black + neutral greys; success
  now uses F5 green #009639; blue/purple/magenta/orange accents wired in
- primary actions keep F5 red #E4002B; Aptos font stack; code on near-black
- ship f5-logo.png in the wheel (force-include) so the branding travels
  with the product, not just this checkout

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat(console): F5 brand reskin — logo, colors, Aptos type
…iene

A 6-reviewer deep dive (bugs / UI / integrations / outputs / hygiene) plus
adversarial verification produced these; version bumped to 0.2.0.

Security & safety:
- refiner (default apply / console Mitigate path) now routes the protected-LB
  check through engine.guard_lb + normalizes the policy name via
  validate_xc_name with a case-insensitive PROTECTED_POLICIES compare, closing
  the raw-membership bypass (NIMBUS-WWW, ./nimbus-www, trailing-slash) and
  restoring the audited override record. (+ regression test)
- mcp `drift` tool: guard the caller-supplied policy path (_is_safe_name +
  is_relative_to) against ../ traversal, matching _tool_apply.
- export.to_csv: neutralize =/+/-/@ spreadsheet-formula-injection cells.

Everyday-user bugs:
- console: /api/results no longer 500s on a mid-write read and the render
  helpers + doAllPrs no-op on a null RESULTS (stuck-Loading crash); poll loops
  stop on 404 instead of spinning forever; OUT snapshotted into the simulate /
  api-schema workers to fix a concurrent-scan run-dir race; /api/emit keeps its
  "corrupt index -> 400" contract via a strict _rj read.
- scan --spec no longer crashes on a list-valued OpenAPI properties/content;
  scan --cve returns a clean error (not a traceback) for an unknown CVE/offline.
- a total discover/provider failure now hard-fails instead of writing a clean
  exit-0 "0 findings" summary.
- apply-waf/apply-dataguard raise a clear "pass --template" error instead of an
  opaque crash on a tenant without the demo object.
- reconcile can retire an auth-protected origin (origin_health no longer rejects
  a 401), treats 5xx as unhealthy, and wires the origin_is_an_lb guard.
- lab-create validates the origin host:port (no traceback on a bad/IPv6 port).
- dependency report renders "none published" instead of the literal "None".

Correctness (low severity): probe login_path default; apply-api-schema orphan
cleanup on any attach failure; simulate --since validation; advisory-alias
self-id; capped-advisory count; version-ordered upgrade target; XC/BigIP client
close()/context-manager.

Packaging / hygiene:
- version 0.1.0 -> 0.2.0 (pyproject + __init__).
- sdist whitelist so pip never ships bench/infra/labs/demo/roadmap material.
- ship config/agents.yaml in the wheel + package-relative fallback in config.py.
- .gitignore: .env*, env-for-new.txt, .claude-flow/, .swarm/.

Suite: 1086 passed, ruff clean; sdist/wheel build verified.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… / footgun)

The shipped default target URL for validate/behavioral/probe/apply-* and the
console action models was hardcoded to the maintainer's XC-fronted lab host, so
a customer who ran any command without --url pointed live exploit/validation
probes at a third party. Replace every occurrence with the neutral placeholder
https://your-app.example.com (matching .env.example) and add
envvar="VPCOPILOT_DEFAULT_URL" to the CLI options so the env drives it — no
baked estate literal anywhere.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…hind advanced mode

Progressive disclosure so a first-time F5 user meets a clean path, without
losing anything for power users / the internal demo:

- ⑦ Benchmark step + the header model switcher are model-evaluation tools
  (internal, stream-1). /api/models now returns `advanced` (true when
  VPCOPILOT_ADVANCED is set OR more than one config/agents*.yaml exists); the
  UI hides both unless advanced. The everyday user sees 6 steps and no switcher;
  the maintainer's multi-model demo is unchanged.
- Scan form: Target repo + Output dir + draft-fixes stay primary; the CVE /
  OpenAPI / dependency-manifest inputs and the confidence/size limits move into
  an "Other inputs & tuning" disclosure.
- Run settings: path prefix, refine attempts, and allow-protected-LB move to an
  "Advanced" disclosure; dry-run / refine / keep-live stay primary.
- Setup: BIG-IP lab + audit sink collapse under "Advanced integrations", leaving
  Credentials + XC status + Agents as the default.
- Review: the cross-product "Emit for another WAF" panel becomes a disclosure so
  the findings table is the focus.

All element ids preserved (no JS behavior change). Verified in both modes via
headless screenshots; suite 1086 passed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
0.2.0: security & correctness quality pass, --url estate fix, UI simplification
…lified UI)

The docs and screenshots still showed the pre-0.2.0 console — the old navy
theme, a permanent seven-step nav, and an always-on model switcher.

- Regenerated the four console screenshots (Review, Simulate, Mitigate, Retire)
  from the canonical demo dataset in the everyday view: F5-branded (black header
  + F5 logo + red accents), six steps, and the new surfaces visible (CWE/OWASP
  mapping on Review, the patch-expiry/TTL table on Retire).
- README console section: "seven steps" -> six; Benchmark + the live model
  switcher reframed as advanced-mode only (VPCOPILOT_ADVANCED or >1 config);
  noted the Advanced disclosures, the F5 branding, and the CVE/manifest/OpenAPI
  scan inputs; retire caption now mentions patch-expiry/reconcile.
- USAGE.md + DEMO.md: same advanced-mode framing for the ⑦ Benchmark step and
  the model switcher.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…for 0.2.0 UI)

docs: refresh console docs + screenshots for the 0.2.0 UI
The shareable report.html still used the pre-0.2.0 navy design system while
the console was already F5-branded. Apply the same brand kit:

- palette → F5 black (was navy) + F5 green success + neutral line/bg; Aptos
  font stack; code blocks on F5 near-black.
- header → F5 black with a red rule and the F5 logo, inlined as a base64
  data: URI (via _f5_logo_uri) so the report stays a single self-contained,
  shareable file — no external assets.
- hero → F5-black gradient with a red left rail; the at-a-glance "band-aids by
  XC control" bars go F5-black and the OWASP-API bars F5-blue.
- regenerated the committed demo/out/report.html sample and README screenshot.

test_report's self-containment check was tightened to forbid only EXTERNAL
resource refs (an inline data: URI is still fully shareable).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…dalone report)

feat(report): F5-reskin the standalone HTML report
… the nimbus target

TRY_IT.md only showed repo-path scans. Add a "More scan inputs" subsection to
Path A covering the other read-only inputs, with portable in-repo fixtures as
the primary examples:

- another repo (incl. the internal nimbus payments app)
- a set of CVEs via --manifest (Nimbus deps fixture: aiohttp==3.9.1 =
  CVE-2024-23334, plus honest handling of unresolvable pins) + single --cve
- an OpenAPI spec via --spec (H3) using bench/fixtures/specs/pay-api.yaml
- OWASP API Top 10 coverage via crAPI + the report's OWASP-API grouping

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…an inputs)

docs(try-it): CVE-set / manifest / spec inputs + OWASP-API + nimbus target
Replace maintainer-estate identifiers with neutral placeholders ahead of
promoting the repo publicly (no functional change):

- XC tenant f5-amer-ent -> your-tenant; namespace d-henley -> your-namespace
  (incl. the committed demo report's XC-dashboard link and the infra module).
- the banknimbus.com estate domain + banknimbus-dev-waf -> example.com /
  example-dev-waf (docs, fixtures, CLI help, apply.py comment, two tests).
- the dhenley@utexas.edu / "dhenley" actor + the local username paths in
  BACKLOG repro commands -> generic placeholders.
- the prior AWS account number and real EC2 instance ids -> redacted.

Kept on purpose (not a live-estate leak, and load-bearing for tests/fixtures/
defaults): the nimbus-vuln-lab benchmark fixture, the nimbus-www / nimbus-waf
functional defaults, the crAPI demo dataset, larkspur-bank, and the public
F5/Canonical marketplace account + AMI ids.

Full suite (1086) green; ruff clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…dentifiers)

chore: scrub live-estate identifiers and PII for public release
Promote BIG-IP from an emit target to a first-class apply target (mitigate ->
validate -> refine -> keep/rollback -> retire). Grounded in a code audit: the
spine is reusable; four glue pieces are new (AS3 wrap, BIG-IP SafeApply spine,
retire/reconcile, FakeBigIP test seam). Part B is a console-first docs plan for
BIG-IP admins who aren't AS3/DevOps people.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…vanced WAF)

The BIG-IP live-apply loop, mirroring the XC one: emit the finding's declarative
WAF policy -> wrap it as AS3 (a base64 WAF_Policy on serviceMain.policyWAF) ->
deploy into the sandbox tenant -> validate against the finding's real exploit ->
keep or roll the tenant back to clean-slate -> ledger/audit. Plus retire (detach
= redeploy without the WAF).

New:
- src/vpcopilot/bigip_apply.py — the AS3 wrap, the SafeApply snapshot/rollback
  against the tenant sub-tree, apply_bigip(), and retire_bigip(). Rollback/retire
  only strip OUR WAF, never a user's pre-existing one.
- CLI: `apply-bigip` / `retire-bigip` (--tenant/--app/--url/--dry-run/--keep,
  guarded by $VPCOPILOT_PROTECTED_BIGIP_TENANTS + /Common).
- tests/conftest.py: FakeBigIP (get_declaration + selective-update deploy) +
  fake_bigip fixture, beside FakeXC.
- tests/test_bigip_apply.py — happy path, rollback-on-fail, keep-off smoke,
  dry-run, honest decline (rate_limit has no AWAF form), protected-tenant guard,
  missing-tenant error, retire. 8 tests, no appliance.

Reused unchanged: the emitter, BigIP.deploy (real dry-run + honest _checked),
guard_tenant, the probe/validator (_run_validation, black-box HTTP), and the
target-neutral ledger/audit spine. Scope: service_policy (the value-constraint
AWAF form); rate_limit/bot/malicious_user are XC-only and decline honestly.

Suite: 1094 passed, ruff clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
docs/BIGIP.md — written for BIG-IP admins (GUI-fluent, not AS3/DevOps): the
safety promise up front (sandbox tenant, dry-run, auto-rollback), a "3 things to
know" primer, a GUI-anchored pre-flight checklist, the connect → sandbox → scan
→ apply → retire flow with each command explained plainly, a plain-language
troubleshooting table, and an honest "what BIG-IP can patch today" scope note.
Linked from the README docs table.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat(bigip): live-apply — apply/retire a band-aid on your own BIG-IP
An "Apply on your own BIG-IP (Advanced WAF)" panel on ④ Mitigate: pick a
service_policy finding, tenant/app/URL, dry-run or keep, and apply — the same
attach → validate-against-the-exploit → keep/rollback loop as the XC buttons,
in the GUI. Fulfils docs/BIGIP.md's "coming: a few clicks, no CLI".

- POST /api/apply-bigip runs bigip_apply.apply_bigip on a worker thread (the
  shared _jobs model), polled through the existing GET /api/action; OUT is
  snapshotted on the request thread like every other action.
- Frontend: the panel + loadBigipApply (populates the finding list from the
  run + a BIG-IP reachability readout) + runBigipApply (post → poll → render
  blocked✓/rolled-back/declined). Behind a disclosure so the everyday XC path
  stays uncluttered; only service_policy findings are offered.
- tests/test_console_bigip.py: the endpoint starts a job, streams the log, and
  reports the result; an appliance error becomes the job's error, not a 500.

Suite: 1096 passed, ruff clean, JS parses; verified in the console screenshot.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Daniel Henley and others added 29 commits August 18, 2026 12:21
…into apply/retire

nginx_lab.py mirrors bigip_lab.py: guard_site (the catch-all `_` refused
unconditionally — the /Common analogue; VPCOPILOT_PROTECTED_NGINX_SITES overridable),
validate_site, create/remove/status. create() writes the copilot-owned vhost — a
reverse proxy to the origin whose location includes /etc/nginx/conf.d/vpcopilot-active/*.conf
(empty = clean slate, App Protect OFF until apply drops a policy), nginx -t, reload,
audit. Idempotent, dry-run stages+rolls back like AS3 dry-run. apply_nginx/retire_nginx
now call guard_site. Nginx client gains ensure_dir. +11 tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…e CLI

Full XC-parity lifecycle for the nginx_app_protect control, mirroring the BIG-IP
wiring at the same four sites the bigip_awaf string touches:

- reconcile: a _retire_nginx branch in _one (before the XC-only presence checks —
  a BYO-NGINX user has no XC), detaching on the box via retire_nginx. Completes
  apply -> validate -> keep -> reconcile -> auto-retire.
- console: POST /api/apply-nginx (NginxApplyReq + _run_nginx_apply, same job model
  as /api/apply-bigip) + a do_retire branch routing nginx_app_protect to retire_nginx.
- report: generalized _bigip_html -> _declarative_waf_html(target, ...), called for
  both bigip-awaf and nginx-app-protect (one code path, two headings); the
  apply_nginx_app_protect impact label.
- cli: nginx-lab {create,rm,status} + apply-nginx + retire-nginx, mirroring the
  bigip-lab/apply-bigip/retire-bigip option surface and exit-code contract
  (LabRefused->3, (NginxError,RuntimeError)->1, 0 iff passed).

+6 tests (reconcile routing, console apply job + retire routing, report NGINX
section, CLI guard exit-3 + registration). Full suite 1157 pass, ruff clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…nd by the live CLI)

The full CLI lifecycle (nginx-lab create -> apply-nginx) on the real box surfaced
two bugs:
- apply_nginx returned {applied:False, dry_run:True} when nginx -t REJECTED the
  staged policy, which the CLI rendered as a benign "would deploy (dry run)" — the
  exact looks-applied-and-is-not false positive. Now it re-raises NginxError, so
  the CLI/console show "box error" and exit non-zero. +1 test.
- nginx_lab.create left the broken vhost on the box when nginx -t failed, breaking
  the next nginx -t. Now it rolls the vhost back (like apply) before re-raising.

Live-proven after the fixes: `vpcopilot nginx-lab create` + `vpcopilot apply-nginx
--finding larkspur-neg-transfer-001` blocks the negative transfer (settle-poll
False,False,True), legit passes, exit 0.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…e CLI

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… resolved

api_schema (disallow off-contract URL) and waf_data_guard (response masking) both
proven via apply-nginx on the box. §10.1 resolved: NAP enforces the declared-URL
disallow immediately (no staging). Form coverage complete: service_policy +
api_schema + waf_data_guard all live-proven. Only §10.5 (reconcile around-the-box
on a single-ingress topology) remains.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… model as BIG-IP

reverse-proxy deployment fires the exploit at the separate origin via TARGETS_ENV
(around the box), like BIG-IP fires at the pool member; retire routing wired +
unit-tested. Single-ingress worry only applies to a co-located deployment (report-
only there, same as any WAF). Task B form coverage complete + full lifecycle proven.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Mirrors Task A's BIG-IP panel for the new enforcement point: an "Apply on your own
NGINX (App Protect)" panel driven by /api/emit (target=nginx-app-protect), so all
three shipped forms are selectable and every decline shows its reason. Wired to
POST /api/apply-nginx (server/location/url + dry-run/keep), streamed through the
shared job model. New GET /api/nginx-lab status endpoint (nginx_lab.status), the
twin of /api/bigip-lab. The report's NGINX section + the ② "Emit for another WAF"
target list already cover NGINX, so console + report now match the BIG-IP surface.

+4 tests (nginx-lab status endpoint, /api/emit panel contract, static page wiring),
node --check clean on the inline JS. Full suite green, ruff clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat(nginx): F5 WAF for NGINX (App Protect) — L2 apply/retire, all 3 forms live-proven
…rial review

A multi-agent bug-hunt of the new code surfaced real impacting defects; fixed with
regression tests (+17):

SECURITY
- Path traversal via finding_id: it lands in on-box file paths and reaches the
  transport from the console /api/apply-nginx body, so a value like
  'x/../../../etc/nginx/nginx' could sudo-write/delete arbitrary root files. Now
  validated (^[A-Za-z0-9_.][A-Za-z0-9_.-]*$) at apply/retire + backstopped by a
  '..'-segment guard in the Nginx client; remove_dir also refuses a non-vpcopilot dir.
- Config injection via origin/location: interpolated raw into the vhost, a value
  with ';{}' could inject a second server block. Now validated (host:port / path).
- DOM XSS: esc() didn't escape quotes; a crafted finding id in a value="..." attr
  could inject a handler in the operator console. esc() now escapes " and '.
- SSH host-key verification was hardcoded off (MITM on the policy-push/root channel
  could forge a 'blocked' verdict). Now TOFU (accept-new) by default, NGINX_SSH_STRICT
  overridable, /dev/null only in explicit 'no' mode.

SAFETY / CORRECTNESS
- An exception after the real apply (a step-3 nginx -t the operator's config now
  rejects, a transient validation/reload error) left an enforcing, un-ledgered
  band-aid (retire/reconcile could never find it) or a config-poisoning include.
  The real-apply body now detaches + reloads before re-raising.
- nginx_lab.remove ran `rm -f` on the managed DIRECTORY (rc=1) → reload+audit never
  ran and the vhost stayed loaded. Uses a new rm -rf remove_dir.
- create dry-run overwrote-then-DELETED an existing live vhost; now preserves/restores
  it (new read_file).
- The vhost hardcoded /etc/nginx/conf.d, so band-aids on a custom NGINX_INCLUDE_DIR
  silently never enforced. The include path now uses the real include_dir.
- get_config swallowed a failed `nginx -T` as an empty config; now raises.
- _await_enforcement re-hammered a failing login for the whole window; now short-
  circuits on auth_failed/no_probe/unobservable-leak. A corrupt spec no longer aborts
  a valid apply. status() computes version() inside the try. default_server is opt-in.

Full suite 1178 pass, ruff clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…NGINX.md, TRY_IT.md

The same declarative band-aid now emits + applies for three enforcement points
(XC, BIG-IP Advanced WAF, F5 WAF for NGINX / App Protect). Docs updated to match:

- README: a "one finding, every enforcement point" section (all three forms proven
  on live BIG-IP + NGINX+App-Protect); the ④ Mitigate note now names the "Apply on
  your own BIG-IP / NGINX" panels; docs/NGINX.md added to the table.
- BIGIP.md: "what it can patch" de-staled — service_policy + waf_data_guard +
  api_schema all live-proven (waf honestly declined for signature staging); the
  console ④ Mitigate panel is shipped, not "coming next".
- NGINX.md (new): the NGINX-admin guide mirroring BIGIP.md — SSH connect, nginx-lab
  create, apply/retire, the guard, troubleshooting, the three forms.
- TRY_IT.md: an "Or: mitigate on your own NGINX (App Protect)" section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…rt, live

Captured against both live appliances (BIG-IP AS3 3.56.0, NGINX Plus R37 + App
Protect) via the console on the demo dataset:

- 4-mitigate.png (updated): the ④ Mitigate step now shows the XC table PLUS the
  "Apply on your own BIG-IP" and "Apply on your own NGINX" panels, both reporting
  ready, with emitter-driven finding dropdowns and the honest declines.
- apply-your-own-waf.png (new): a focused shot of both apply panels — used in the
  README hybrid-fabric section and both admin guides.
- report-bigip-nginx.png (new): the report's BIG-IP Advanced WAF + F5 WAF for NGINX
  sections — same finding, form emitted, honest declines.

README / BIGIP.md / NGINX.md reference them; the demo report is regenerated with the
NGINX section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Quality hardening (adversarial review) + BIG-IP/NGINX docs & screenshots
The ④ Mitigate "Apply on your own NGINX" panel + its help told the operator to set
NGINX_SSH_* "in ⚙ Setup", but Setup had no NGINX fields — the only way to point it
at the box was hand-editing .env. Added the NGINX_SSH_* keys to MANAGED_KEYS (so the
generic Setup config editor renders them as fields) with NGINX_SSH_PASSWORD in
SECRET_KEYS (the key PATH is not secret), plus a NGINX + App Protect card in Setup's
Advanced integrations with a live status readout (loadNginx → /api/nginx-lab),
mirroring the BIG-IP card. +2 tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…C dashboard link

The persistent hero band (console + standalone report) mixed real scan-derived
numbers with two things that were not the user's data:

- a fixed "vs 25 days normal change control · N× faster" contrast
  (CHANGE_CONTROL_DAYS defaulted to 25 — a narrative baseline, not a scan number)
- a hardcoded "mitigated live by XC" label, wrong now that a band-aid can land
  on BIG-IP or NGINX

And a persistent "XC security dashboard ↗" link the operator asked to remove.

Changes:
- change_control_days() returns None when CHANGE_CONTROL_DAYS is unset; impact()
  omits the contrast and the derived speedup unless the operator opts in.
- impact() exposes points_live (bigip_awaf→BIG-IP, nginx_app_protect→NGINX, else
  XC), derived from the same set the mitigated count uses so label and number
  never disagree; the hero label reads "mitigated live · <point>".
- Remove the XC dashboard link + its plumbing (hero DASHBOARD var, /api/defaults
  `dashboard` field). xc_dashboard_url() helper kept (still tested).

Full suite: 1182 passed, 15 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… from infrastructure state

The Retire tab mixed data across sessions: a 5-day-old band-aid applied to one app showed up
beside a later scan of a different app. Root cause — live band-aids lived in the per-session
ledger, and init_from_scan had to LEAK them across scans (the old "never orphan a live patch"
keep-block) so reconcile could still find them. That leak is the mixing.

Split the two kinds of state:
- a SESSION owns ephemeral scan artifacts (findings/triage/policies/report) + a ledger that is
  now scoped STRICTLY to that scan's findings (leak removed).
- a global inventory.json is the session-independent record of what band-aid is attached to which
  LB/appliance, its TTL + cure — written on apply, cure attached on remediate, retired on retire.
  Retire + reconcile read it, always; a live patch can no longer be orphaned because it lives here.

Mechanics:
- new inventory.py (keyed by finding_id; entry mirrors a ledger entry + `session` provenance).
- ledger.mark_mitigated/remediated/retired WRITE THROUGH to inventory, so none of the ~10 apply
  call sites change; init_from_scan's cross-session keep-block is deleted.
- reconcile + retire + list_patches read the global inventory; reconcile resolves each entry's own
  `session` for its probe spec + audit trail, and its pass-lock is now global. A pass/list also
  auto-migrates the given out_dir's live patches (idempotent safety net).
- console: Retire tab is now two labeled sections — a cross-session "Live band-aids on your
  infrastructure" list (control @ target · applied date · TTL, with Retire) over a read-only
  "This session's findings" track; do_retire routes by the inventory entry (cross-session); a
  lifespan startup seeds the inventory from existing out* dirs (one-time migration).
- inventory.json / reconcile.lock gitignored (runtime state); autouse test fixture isolates the
  inventory dir per test.

Full suite: 1194 passed, 15 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… a live band-aid

Adversarial review caught the split re-introducing the exact orphaning it set out to kill:
the inventory was keyed by finding_id alone, but finding_ids are per-scan LLM slugs that recur
across apps (the repo's own ledgers show neg-pay-001 in out/, out-dgx/, out-claude/). Two live
band-aids sharing a slug on different LBs collapsed into one row — the other stayed physically
attached but vanished from Retire + reconcile.

- key the inventory by lb + finding_id (`_key`); record_mitigated / record_reconcile / mark_retired
  address one band-aid, and migrate_from_dirs keys the same way (fixing the first-dir-wins mirror).
- attach_cure (was record_remediated) attaches a merged cure to EVERY LB the finding was patched on
  — a code fix cures it everywhere — and still mints nothing for a code-cure-only finding.
- retire gains an `lb` selector end-to-end (retire_finding / console do_retire+RetireReq / CLI --lb /
  MCP): given only a finding_id it retires the single live match, and REFUSES (naming the LBs) when
  a slug is live on two — detaching the wrong control would re-expose an app. The Retire tab passes
  each row's lb; its retire-status id is now keyed by finding_id+lb (two rows can share a slug).
- appliance retires (bigip/nginx) update the inventory explicitly with their reconstructed lb, since
  ledger.mark_retired no longer writes through (it lacks the lb).

Also from the review:
- reconcile now migrates out_dir AND its sibling session dirs, so a headless CLI/cron pass picks up
  a pre-split band-aid recorded in another session (was: console-only).
- reconcile's "already detached" retire branch advances the session ledger too, so impact()'s
  per-session hero stops counting a detached band-aid as live.

Full suite: 1198 passed, 15 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat(console): NGINX connection fields in ⚙ Setup
fix(hero): make the top strip reflect the user's own scan, drop the XC dashboard link
CI runs `ruff check src tests` (I'd only run pytest locally). Three errors:
- reconcile.py: the composite-key change left the loop var `key` unused (B007) in
  the reconcile driver and list_patches — renamed to _k (still sorts by the key).
- test_console_inventory.py: unused `import time` (F401).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…space

The final piece of the session/inventory split: make the active scan session a first-class,
visible thing so the session-scoped tabs can never silently show two runs.

- A session is an out* dir. GET /api/sessions lists every workspace (findings count, friendly name,
  active flag); POST /api/session opens an existing one or creates a fresh named one (out-<slug> +
  session.json), setting the OUT the read/scan endpoints use.
- Header gains a session selector + "+ New"; switching hard-reloads so every tab repopulates from
  the chosen session, and a scan defaults its output dir to the active session.
- open is guarded to an allowlist of discovered dirs (no path traversal); new slugifies the name.

Agent-native parity: a read-only MCP `sessions` tool lists the same workspaces (an agent targets a
session via the `out` param every tool already takes), and the MCP `retire` tool now exposes the
`lb` selector the CLI/console gained, so an agent can disambiguate a finding live on two LBs.

Full suite: 1206 passed, 15 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… create-session gap

Adversarial review of the named-sessions feature (2 finders found nothing — traversal guard and
XSS escaping held):

- A summary.json/session.json that is valid JSON but NOT an object (null / 42 / a list) made
  {}.update(loaded) raise TypeError/ValueError, uncaught — 500-ing all of /api/sessions and the MCP
  `sessions` tool over ONE damaged file. New shared `sessions.read_meta` returns {} for a missing,
  unparseable, OR non-object sidecar; both surfaces use it.
- Agent-native parity gap: the console's 'New session' writes a friendly session.json name, but no
  MCP tool could create a named session — an agent could read the name it can't set. New WRITES_OUT
  `session_new` tool creates out-<slug> + session.json via the SAME shared helper the console now
  uses (`sessions.create_session` / `slugify`), so the slug rules and metadata shape can't drift.

Full suite: 1209 passed, 15 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat(console): named sessions — explicit, switchable active scan workspace
chore: land the session/inventory + named-sessions work into main (recovery for #60/#61)
Two changes to the shipped surfaces, plus the version roll.

**The F5 logo is gone from every UI screen.** The console header and the standalone HTML
report carried `f5-logo.png`; both now draw a neutral shield-and-patch mark instead. The
asset, its `/f5-logo.png` route and its wheel force-include are removed, and the report's
mark is inline SVG rather than a base64 PNG — so the report stays a single self-contained
file with no external resource loads, which `tests/test_report.py` asserts. The README's
"F5-branded" claims went with it.

**Three generated flow diagrams**, in `docs/images/` with their sources in
`docs/images/src/`:

- `flow-hero.svg` — four acts, big type. Sized so it survives GitHub rendering a README
  image at ~880px, which is the binding constraint; it sits at the top of the README.
- `flow-pipeline.svg` — the detailed pipeline: scan input, all eight agents with the
  self-heal loop, the three enforcement points with their real control matrix, and the
  lifecycle strip. Replaces the ASCII sketch under "How it works" and is linked full-size.
- `flow-control-plane.svg` — the copilot as a control plane reaching down into the F5 data
  plane with three verbs (apply / validate / retire). Added to `DESIGN.md`.

They are generated, not hand-drawn, so a pipeline change is an edit rather than a re-draw.
`svgkit.py` emits presentation attributes only — no `<style>`, no CSS classes, no external
refs — because GitHub sanitises SVG served through `<img>`, and it paints an explicit white
background because a transparent SVG is unreadable against the dark theme.

The control matrix in the diagrams is read off `emitters.py`, not invented: XC carries all
seven controls; BIG-IP AWAF and NGINX App Protect carry `service_policy`, `waf_data_guard`
and `api_schema`, and decline the other four with a stated reason.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ey8yTg3mHafoMcVkZYFg1N
The logo removal missed the most-seen UI screens: the README and DEMO screenshots
were pictures of the old header. `2-review`, `3-simulate`, `6-retire` and `report`
all carried `f5-logo.png`; `1-scan` predated the current header entirely.

Re-captured from the demo dataset at the originals' resolution — 1200 logical px at
deviceScaleFactor 2, so they stay 2400px wide — with trailing background rows trimmed.
`6-retire` is taller than before because the retire step now shows the live band-aid
inventory that 0.3.0 added.

`4-mitigate`, `apply-your-own-waf` and `report-bigip-nginx` are panel crops with no
header, so they were already clean and are untouched.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ey8yTg3mHafoMcVkZYFg1N
…an't strand it

The logo removal missed every documentation screenshot, which is a repeatable trap:
those PNGs are pictures of the product, nothing verifies them, and they are the first
thing a README reader sees. `shoot_screenshots.py` captures the four console steps and
the report at the committed resolution and trims the padding a full-page capture adds.

It clicks the step nav rather than setting `location.hash` — a bare hash change is a
same-document navigation and does not re-run the console's router, so the first attempt
at this silently captured the Review step four times. It asserts the active section
afterwards for the same reason: the wrong step looks plausible in review.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ey8yTg3mHafoMcVkZYFg1N
release: 0.3.0 — drop the F5 logo from the UI, add the flow diagrams
The SVGs stay the source of truth and stay what the README and DESIGN.md embed — GitHub
scales them crisply and they are a few tens of kilobytes. But PowerPoint, Keynote, LinkedIn,
Substack and most email clients will not take an SVG, and promoting the project means putting
these diagrams in exactly those places.

`render_png.py` renders each `flow-*.svg` to a PNG beside it through the headless Chromium
that `shoot_screenshots.py` already needs. Default 2x, so the hero lands at 2800px and the
pipeline at 3200px — enough for a full-bleed slide — with `--scale` for print.

It inlines the SVG into the page rather than pointing an `<img>` at a `file://` URL: with
`set_content` the page origin is `about:blank`, and Chromium refuses a `file://` subresource
from there. The first run of this produced three plausible-looking blank PNGs with a broken-
image icon in the corner, which reads as a bad diagram rather than a blocked fetch.

Also shortened the three verb sub-labels in the control-plane diagram. At 10px the old strings
ran into the next verb's label, so "apply", "validate" and "retire" read as one sentence.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ey8yTg3mHafoMcVkZYFg1N
docs(images): ship a PNG of each flow diagram alongside the SVG
@vtobi
vtobi merged commit a6fbb35 into f5devcentral:main Oct 2, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants