SEC-B12: blacklist incident decision tree and rollback runbook (#400) #924

2026-06-19T10:57:40Z

PlasticDigits commented

2026-06-19 10:57:40 +00:00

(Migrated from gitlab.com)

Summary

Adds operator documentation for SEC-B12 (GitLab #400): an incident blacklist decision tree and false-positive rollback runbook covering wallet (confirmed exploit actor / documented ToS violation), token (malicious CW20), and pair (compromised pool) criteria, plus mandatory evidence preservation before Unblacklist*.

Changes:

New docs/runbooks/blacklist-decision.md with mermaid decision tree, severity hints, classification criteria, rollback checklist, and execution reference
docs/templates/incident-dex-indexer.md Mitigation step links to the runbook
Cross-links from docs/security-model.md, docs/adr/0003-governance-trading-blacklist.md, docs/README.md
Agent playbook skills/AGENTS_BLACKLIST_DECISION.md
Drift guard: make check-blacklist-decision-docs + make verify-issue-400 (added to make lint)

Related to #400.

Acceptance checklist

Criterion	Verification	Result
Decision criteria for wallet blacklist (confirmed exploit actor)	`grep -q 'Confirmed exploit actor' docs/runbooks/blacklist-decision.md`	PASS
Decision criteria for token blacklist (malicious token behavior)	`grep -q 'Malicious CW20' docs/runbooks/blacklist-decision.md`	PASS
Decision criteria for pair blacklist (compromised pair)	`grep -q 'Compromised pool' docs/runbooks/blacklist-decision.md`	PASS
False-positive rollback requires evidence preservation	`grep -q 'Preserve original evidence' docs/runbooks/blacklist-decision.md`	PASS
Decision document linked from incident template Mitigation step	`grep -q 'blacklist-decision.md' docs/templates/incident-dex-indexer.md`	PASS
Developer reviewed criteria match governance policy	Manual review of runbook vs ADR 0003 + security-model blacklist section	PASS

Automated gate: make verify-issue-400 → 4/4 PASS.

Verification checklist (third parties)

make check-blacklist-decision-docs
make verify-issue-400
make check-user-incident-faq-docs   # ensure user FAQ not duplicated

Manual:

Open docs/runbooks/blacklist-decision.md — confirm decision tree covers wallet / token / pair / ToS branches and rollback checklist.
Open docs/templates/incident-dex-indexer.md § Mitigation — confirm link to blacklist runbook.
Confirm docs/security-model.md § Trading blacklist links to operator runbook (not duplicating user FAQ).

## Summary Adds operator documentation for **SEC-B12** (GitLab #400): an incident **blacklist decision tree** and **false-positive rollback runbook** covering wallet (confirmed exploit actor / documented ToS violation), token (malicious CW20), and pair (compromised pool) criteria, plus mandatory evidence preservation before `Unblacklist*`. Changes: - New [`docs/runbooks/blacklist-decision.md`](docs/runbooks/blacklist-decision.md) with mermaid decision tree, severity hints, classification criteria, rollback checklist, and execution reference - [`docs/templates/incident-dex-indexer.md`](docs/templates/incident-dex-indexer.md) Mitigation step links to the runbook - Cross-links from [`docs/security-model.md`](docs/security-model.md), [`docs/adr/0003-governance-trading-blacklist.md`](docs/adr/0003-governance-trading-blacklist.md), [`docs/README.md`](docs/README.md) - Agent playbook [`skills/AGENTS_BLACKLIST_DECISION.md`](skills/AGENTS_BLACKLIST_DECISION.md) - Drift guard: `make check-blacklist-decision-docs` + `make verify-issue-400` (added to `make lint`) Related to #400. ## Acceptance checklist | Criterion | Verification | Result | |-----------|--------------|--------| | Decision criteria for wallet blacklist (confirmed exploit actor) | `grep -q 'Confirmed exploit actor' docs/runbooks/blacklist-decision.md` | PASS | | Decision criteria for token blacklist (malicious token behavior) | `grep -q 'Malicious CW20' docs/runbooks/blacklist-decision.md` | PASS | | Decision criteria for pair blacklist (compromised pair) | `grep -q 'Compromised pool' docs/runbooks/blacklist-decision.md` | PASS | | False-positive rollback requires evidence preservation | `grep -q 'Preserve original evidence' docs/runbooks/blacklist-decision.md` | PASS | | Decision document linked from incident template Mitigation step | `grep -q 'blacklist-decision.md' docs/templates/incident-dex-indexer.md` | PASS | | Developer reviewed criteria match governance policy | Manual review of runbook vs ADR 0003 + security-model blacklist section | PASS | Automated gate: `make verify-issue-400` → **4/4 PASS**. ## Verification checklist (third parties) ```bash make check-blacklist-decision-docs make verify-issue-400 make check-user-incident-faq-docs # ensure user FAQ not duplicated ``` Manual: 1. Open [`docs/runbooks/blacklist-decision.md`](docs/runbooks/blacklist-decision.md) — confirm decision tree covers wallet / token / pair / ToS branches and rollback checklist. 2. Open [`docs/templates/incident-dex-indexer.md`](docs/templates/incident-dex-indexer.md) § Mitigation — confirm link to blacklist runbook. 3. Confirm [`docs/security-model.md`](docs/security-model.md) § Trading blacklist links to operator runbook (not duplicating user FAQ).

PlasticDigits commented

2026-06-19 11:00:14 +00:00

(Migrated from gitlab.com)

Security review — MR !924

Commit reviewed: 3a6834f0bbb6c2b42693cd937f24cabeb9570560
Scope: Documentation and CI drift guards only — docs/runbooks/blacklist-decision.md, cross-links in ADR/security-model/incident template/README/testing, skills/AGENTS_BLACKLIST_DECISION.md, scripts/check_blacklist_decision_docs.py, scripts/qa/verify-issue-400.sh, Makefile lint/verify-issue-400 targets.

Method: Full MR diff review; traced attacker-controlled input to sinks (none present in changed code). Prior MR security threads: none.

Outcome: FINDINGS: 0 medium+

No inline threads — no exploitable paths identified on this diff.

Areas examined

Category	Result
Injection (shell/SQL/JSON)	N/A — Python/bash scripts use fixed repo-relative paths; no external input
Authn/authz bypass	No runtime auth changes
Secret leakage / unsafe logging	Runbook uses placeholders (`<factory>`, `<terra1...>`); no credentials
SSRF / XSS / CSRF / path traversal	No web or network code modified
Deserialization / supply chain	No new dependencies
On-chain permission boundaries	Docs reference existing governance-only `Blacklist` / `Unblacklist` messages (ADR 0003); no contract or indexer handler changes

The runbook’s reference to GET /api/v1/compliance/blacklist-check documents a pre-existing read-only compliance probe; this MR does not alter that endpoint.

Security review: no medium+ findings on this diff.

## Security review — MR !924 **Commit reviewed:** `3a6834f0bbb6c2b42693cd937f24cabeb9570560` **Scope:** Documentation and CI drift guards only — `docs/runbooks/blacklist-decision.md`, cross-links in ADR/security-model/incident template/README/testing, `skills/AGENTS_BLACKLIST_DECISION.md`, `scripts/check_blacklist_decision_docs.py`, `scripts/qa/verify-issue-400.sh`, Makefile `lint`/`verify-issue-400` targets. **Method:** Full MR diff review; traced attacker-controlled input to sinks (none present in changed code). Prior MR security threads: none. **Outcome:** `FINDINGS: 0` medium+ No inline threads — no exploitable paths identified on this diff. ### Areas examined | Category | Result | |----------|--------| | Injection (shell/SQL/JSON) | N/A — Python/bash scripts use fixed repo-relative paths; no external input | | Authn/authz bypass | No runtime auth changes | | Secret leakage / unsafe logging | Runbook uses placeholders (`<factory>`, `<terra1...>`); no credentials | | SSRF / XSS / CSRF / path traversal | No web or network code modified | | Deserialization / supply chain | No new dependencies | | On-chain permission boundaries | Docs reference existing governance-only `Blacklist*` / `Unblacklist*` messages (ADR 0003); no contract or indexer handler changes | The runbook’s reference to `GET /api/v1/compliance/blacklist-check` documents a pre-existing read-only compliance probe; this MR does not alter that endpoint. **Security review: no medium+ findings on this diff.**

PlasticDigits commented

2026-06-19 12:45:40 +00:00

(Migrated from gitlab.com)

mentioned in commit 3446b3332a

mentioned in commit 3446b3332af5d1b41c5847ef796e01c06a568319