Pre-public release audit (v1.3.36.8)¶

Read-only audit of the argos-edge repo before gh repo edit --visibility public. This page is the PHASE 0 deliverable; PHASE 1 fixes are deferred to a separate decision.

Audit date: 2026-05-03 Audit scope: README, CLAUDE.md, docs/ portal, CHANGELOG, sanitization sweep, public-readiness checklist Reference release: v1.3.36.8 (latest tag), v1.3.35 (latest panel binary)

Executive summary¶

Recommendation at audit time: NOT yet safe to flip public. Four gating items bundled into v1.3.37 doc/ hygiene release.

Status post-v1.3.37: all four gating items RESOLVED — see Resolution below for the per-item fix mapping.

Resolution¶

v1.3.37 (2026-05-03, doc + sanitization release; tooling-only, panel binary unchanged at v1.3.35) addressed every gating item above:

Items 6-9 (operator decision: defer post-public). Item 5 (LICENSE Licensor name) is intentional + legally-required; Pattern D explicitly excludes LICENSE so the regression-guard won't flag it.

Critical findings¶

C1 [HIGH] — TODO(kilian) markers leak operator's real first name¶

Severity: high (operator PII in source). Effort: S (~10 min mechanical replace + script update).

check-no-personal-data.sh covers three patterns (cmos486.es, operator LAN 192.168.{3,5}.x, gmail handle discodurovirtualk) but does not catch the operator's real first name when it appears in TODO(kilian) markers. Sweep results:

Recommended fix: replace TODO(kilian) with TODO or TODO(maintainer) across the 5 source files; leave the CHANGELOG line alone (it documents a past sweep that itself used the marker — historical context, not a leak to future readers if the markers themselves are removed from active code; alternatively rephrase to "marked 5 ambiguous ones with TODO comments").

Also: extend check-no-personal-data.sh with Pattern D = \bkilian\b (case-insensitive, word-boundary) to enforce the regression-guard. This matches the eight-strike pattern: catch the foot-gun once, codify in the gate, can't sneak back.

C2 [INFO, not a leak] — LICENSE Licensor name¶

LICENSE lines 12 + 14 contain "Kilian Ubeda" as the named licensor and copyright holder:

Licensor:             Kilian Ubeda (cmos486)
Licensed Work:        argos-edge 1.0.0
                      The Licensed Work is (c) 2026 Kilian Ubeda.

Verdict: NOT a leak. A BSL 1.1 license requires a named licensor for legal validity, and the copyright notice on a published work follows the same convention. This is intentional. No action needed, but flagging for awareness when reviewing the TODO(kilian) regression-guard pattern (Pattern D must not flag LICENSE; add an explicit exception).

Stale documentation findings¶

S1 [MEDIUM] — CLAUDE.md is 3 minor versions behind reality¶

Effort: M (~20 min). Read CLAUDE.md once, refresh five version markers, recount smoke scripts (18 = 13 original + 4 v1.3.32 + capture-automation.sh + country-reconciler.sh + deploy-rebuild.sh + demo-environment.sh — verify the categorization).

S2 [MEDIUM] — verification-report.md cites old version + smoke count¶

docs/operations/verification-report.md:

This page is the single-source verification gate for public release per its own opening line. It must be refreshed before flipping public, not after.

Effort: M (~30-45 min). Re-tabulate per-feature smoke matrix; verify each smoke script still covers the documented EFFECT. Some smokes added v1.3.32-v1.3.36 (country-reconciler.sh v1.3.33, capture-automation.sh v1.3.36.x, demo-environment.sh v1.3.35, deploy-rebuild.sh v1.3.34.3, lapi-flush-cap.sh v1.3.33, scenario-descriptions.sh v1.3.30) need rows.

S3 [LOW] — docs/screenshots/README.md carries 9× TODO embed in features/X.md¶

Inventory tracking notes flagging features pages that have eligible screenshots but no ![]() embed yet:

features/crowdsec.md           — 4 screenshots awaiting embed
features/security-overview.md  — 3 screenshots awaiting embed
features/drift-detection.md    — 1 screenshot awaiting embed
features/country-bans.md       — 1 screenshot awaiting embed

Verdict: not a public-release blocker (pages render fine without embeds; text content covers the feature). Operator workflow in progress. Can be addressed incrementally post-public.

Effort: S per page (5 min each = ~45 min total) but not gating.

Public-readiness gaps¶

P1 [MEDIUM] — SECURITY.md missing (responsible disclosure policy)¶

argos-edge is a security tool (WAF + reverse proxy + SSO). Visitors expect a vulnerability-reporting policy. GitHub looks for SECURITY.md at:

• root
• .github/
• docs/

None present. When GitHub finds it, the repo gets a "Security" tab with a "Report a vulnerability" button backed by the policy text.

Effort: M (~30 min). Recommended content:

• Supported versions (latest minor + N-1)
• Reporting channel (GitHub Security Advisories or email)
• Expected response SLA
• Disclosure timeline policy (90-day default? coordinated?)
• Out-of-scope (homelab self-hosted scope, not cloud service)
• Hall of fame / acknowledgements section (optional)

For a solo-maintained homelab project, a 1-page SECURITY.md is appropriate; cribbing the GitHub Security Advisory pattern is fine. Place at root or .github/.

P2 [LOW] — .github/ISSUE_TEMPLATE/ missing¶

Optional but helpful for filtering bug-vs-feature reports + reducing back-and-forth on "what version / what panel mode / what stack". Recommended templates:

• bug_report.md: version, panel mode, stack components, reproduction
• feature_request.md: use case, alternatives considered

Effort: S (~15 min). Not a blocker for public flip.

P3 [LOW] — .github/PULL_REQUEST_TEMPLATE.md missing¶

Optional. If solo-maintained accepts no PRs in practice, can skip; if PRs are welcome, a 1-page template (description, smoke results, sanitization verification) sets expectations.

Effort: S (~10 min). Not a blocker.

P4 [INFO] — CONTRIBUTING.md placement¶

GitHub recognizes CONTRIBUTING.md at root, .github/, or docs/. argos-edge has it at docs/CONTRIBUTING.md, which IS recognized. Symlink or move to root only if you want the link to render in the GitHub PR-create flow with shorter path. Not gating.

What's already clean¶

• README.md — narrative is coherent (title → tagline → hero → why → features → quickstart → access modes → arch → verifying → docs → license). Hero shot embedded as of commit 8b5475e (today). Quickstart commands current. License + BSL 1.1 conversion date documented.
• CHANGELOG.md — Keep a Changelog format throughout; 61 entries from v1.0.0 to v1.3.36.8; latest entry matches today's tag.
• docs/CONTRIBUTING.md — well-written, sanitization- focused, codifies placeholder conventions (RFC 2606 + RFC 5737).
• mkdocs.yml — nav coherent; 110 published pages; release-notes section complete; exclude_docs correctly scopes out internals/, planning/, screenshots/README.md, CONTRIBUTING.md.
• .github/workflows/ — three workflows (docs.yml, personal-data-guardrail.yml, release.yml). No inline secrets; standard ${{ secrets.* }} references.
• Docs portal cross-refs — Explore agent verified zero broken internal links across 268 markdown links.
• Image embeds — all 14 referenced screenshots exist in docs/screenshots/.
• Per-feature doc currency — feature pages (drift-detection, country-bans, appsec, crowdsec, reverse-proxy, etc.) reflect v1.3.36.x feature set. Provenance markers ("v1.3.27 added", "v1.3.31 async") are correct historical context, not staleness.
• CAPTURE-automation flow — operator workflow for sanitized screenshots is documented in docs/screenshots/README.md and codified in scripts/capture/.

Recommendation: priority order¶

Bundled release recommendation: ship items 1-4 as v1.3.37 (doc + sanitization release; tooling-only, argosVersion stays 1.3.35.4). Estimated total effort: 2-3 hours. Items 5-8 can ship as v1.3.37.x or folded into next feature release.

After v1.3.37 ships, the repo is publication-ready.

What was checked¶

Notes for the future¶

• Pattern D addition to check-no-personal-data.sh closes the gap that let TODO(kilian) markers survive 36+ releases. Adding new patterns to the gate is the v1.3.15 contract — patterns codify lessons.

• Verification-report cadence: the page is meant to be re-run on "any future release that might regress a covered surface" per its own opening, but in practice it has frozen at v1.3.32. A lightweight cron-style pre-tag checklist ("did the smoke matrix grow / a smoke change behavior?") would prevent the next N-version drift.

• CLAUDE.md update cadence: this is operational onboarding for future Claude sessions; staleness there compounds the "Eight-strike pattern" problem (now eleven). Refresh per-quarter or per-major-feature set, not per-release.