DECNET/TODO.md

TODO — credential reuse + vectorstore (handoff)

This document hands off in-progress work on the credential reuse patterns task from development/DEVELOPMENT.md (under Service-Level Behavioral Profiling) plus the decnet/vectorstore/ scaffolding that prepares the substrate for a future statistical re-identification engine over behavioral fingerprints. See /home/anti/.claude/plans/ah-excellent-alright-claude-vivid-thimble.md for the full approved plan and motivation.

Done in the previous session

Foundation is shipped + tested (26 new tests passing, no regressions):

• Schema — decnet/web/db/models/logs.py
  • Credential.attacker_uuid: Optional[str] FK to attackers.uuid, nullable. Backfilled by the profiler post-write.
  • CredentialReuse table (UUID PK; JSON list columns for attacker_uuids, attacker_ips, deckies, services; target_count, attempt_count, confidence reserved for future fuzzy matching). Unique key: (secret_sha256, secret_kind, principal_key).
  • CredentialReuseResponse Pydantic DTO.
• Repo — decnet/web/db/sqlmodel_repo.py + repository.py
  • upsert_credential_reuse(...), list_credential_reuses(limit, offset, min_target_count, secret_kind), get_credential_reuse_by_id(id), update_credential_attacker_uuid(attacker_ip, attacker_uuid) -> int.
  • Rename: pre-existing get_credential_reuse(secret_sha256) → get_credential_attempts_for_secret(secret_sha256). All callers updated.
• Bus topics — decnet/bus/topics.py
  • CREDENTIAL_CAPTURED = "captured" (one per Credential upsert).
  • CREDENTIAL_REUSE_DETECTED = "reuse.detected" (correlator emits on insert/grow).
  • credential(event_type) builder.
• Vectorstore — decnet/vectorstore/ (NEW; flat layout mirroring decnet/bus/)
  • base.py — BaseVectorStore ABC, VectorRecord, Neighbor, VECTORSTORE_SCHEMA_VERSION. Methods: initialize, close, health, insert, get, delete, knn. Keyed by (kind, id).
  • fake.py — FakeVectorStore (in-memory, brute-force L2 KNN) + NullVectorStore (no-op when DECNET_VECTORSTORE_ENABLED=false).
  • sqlite_vec.py — SqliteVecVectorStore; lazy-loads the sqlite_vec extension; one vec0 virtual table per kind so new feature families don't require schema migration. Per-kind dim is locked on first insert.
  • factory.py — get_vectorstore() env-driven dispatch (DECNET_VECTORSTORE_TYPE ∈ {sqlite_vec, fake}; DECNET_VECTORSTORE_ENABLED; DECNET_VECTORSTORE_PATH). On missing sqlite_vec extension: logs a warning and returns FakeVectorStore so workers don't crash.
• Tests
  • tests/db/test_credential_reuse.py — 11 tests (upsert idempotency, list filters/pagination, FK backfill semantics, null-principal uniqueness, JSON-list merging).
  • tests/vectorstore/test_factory.py (6) + tests/vectorstore/test_fake.py (9) — factory dispatch + fallback, round-trip, dim-mismatch raises, KNN ordering, NullStore no-op.
  • Updated tests/db/test_base_repo.py and tests/db/test_credentials.py for the rename.

Not yet done — what the next agent should pick up

Tasks below are roughly in dependency order. Backend first, dashboard last (it's the largest unknown and benefits from a fresh context).

1. Profiler backfill of Credential.attacker_uuid

Smallest task; do this first to validate the FK column end-to-end.

• File: decnet/profiler/ — find the spot where the profiler mints/updates an Attacker row from observed events. There's likely an upsert_attacker(...) call that produces the (ip, uuid) pair.
• Add immediately after a successful upsert:

  await repo.update_credential_attacker_uuid(ip, uuid)
  

• Test in tests/profiler/ (whatever the existing test file is) that after the profiler processes events for an IP, all Credential rows for that IP have their attacker_uuid populated. Use the pattern from tests/db/test_credential_reuse.py:: test_update_credential_attacker_uuid_backfills_only_nulls.

2. Correlator engine + worker wiring

• File: decnet/correlation/engine.py — add correlate_credential_reuse(min_targets: int = 2) to CorrelationEngine. Signature suggested in the plan:

  SELECT secret_sha256, secret_kind, principal,
         COUNT(DISTINCT decky_name||':'||service) AS target_count
  FROM credentials
  GROUP BY secret_sha256, secret_kind, principal
  HAVING target_count >= :min_targets
  

  For each group, fetch the underlying credential rows and call repo.upsert_credential_reuse(...) per row. The repo upsert recomputes target_count from the credentials table on each update, so you don't need to pass aggregates in.
• On insert/grow (out["inserted"] is True or out["changed"] is True), publish bus.publish(topics.credential(topics.CREDENTIAL_REUSE_DETECTED), {...}) with payload {id, secret_kind, target_count, attacker_uuids, attacker_ips, deckies, services}.
• Worker file: decnet/correlation/main.py (or wherever CorrelationEngine is loop-driven). Subscribe to:
  • attacker.observed — re-runs reuse pass for that IP.
  • credential.captured — re-runs reuse pass for that secret.
  • Heartbeat tick every 60s as a fallback (mirror the mutator's bus-wake + slow-tick pattern).
• Where is credential.captured emitted? Find the credential ingest path — probably decnet/collector/ or wherever repo.upsert_credential(...) is called. Add a bus.publish( topics.credential(topics.CREDENTIAL_CAPTURED), {secret_sha256, secret_kind, attacker_ip, decky, service}) after a successful upsert. Bus is fire-and-forget — don't block on it.
• Tests:
  • tests/correlation/test_credential_reuse.py — engine emits the right CredentialReuse rows from synthetic credentials; bus event published exactly once per insert/grow.
  • Use decnet.bus.fake.FakeBus in tests; collect published events for assertion.

3. API routes — GET /api/v1/credential-reuse

• File: probably decnet/web/api/routes/ — see how existing credentials routes are organized (recent commit feat(api): GET /credentials endpoint → 4566146).
• Endpoints:
  • GET /api/v1/credential-reuse?limit=50&offset=0&min_target_count=2&secret_kind=plaintext → CredentialReuseResponse (already in models).
  • GET /api/v1/credential-reuse/{id} → single row dict, 404 if missing.
• JWT-gated like all other routes. Use the existing dependency.
• No POST/PUT/PATCH — read-only this release. Per the feedback_schemathesis_400 memory there's no 400 contract to document since there's no body parsing.
• Tests: tests/api/test_credential_reuse_routes.py — JWT gate, pagination, filters, 404 for missing id.

4. Dashboard — Credentials Reuse tab + drawer

The big unknown. Next agent should:

1. Survey decnet/web/dashboard/ (React app) — how the existing Credentials view is structured (commit 4ea4b0b feat(web): Credentials view + inspector).
2. Add a "Reuse" tab/filter that lists CredentialReuse rows sorted by target_count desc.
3. Drawer on row-click showing decky×service breakdown, attacker_uuid list (link to /attackers/:id), timeline. Reuse the existing drawer pattern (see feedback_react_stop_propagation_native_delegation memory — backdrop click closes via target===currentTarget, never stopPropagation).
4. On the existing Credentials list, add a "seen on N targets" badge when a credential has a corresponding CredentialReuse row, so the connection is bidirectional.

5. DEVELOPMENT.md

Tick [x] Credential reuse patterns under Service-Level Behavioral Profiling. Add a one-liner under Attacker Intelligence Collection noting decnet/vectorstore/ is scaffolded for the future statistical re-ID engine (no behavioural change yet).

Architectural decisions worth knowing

These came out of the design conversation that produced the plan; the next agent should respect them:

• Classical statistics, not ML, for attacker re-identification. Cosine/Mahalanobis/KS-test over per-kind feature vectors, weighted voting, versioned thresholds. Reproducible, explainable, no model drift. ML is reserved for a future advisory layer behind the factory, never primary.
• Provider factory pattern is mandatory for any new pluggable backend (storage, transport, similarity). Mirror decnet/web/db/ and decnet/bus/ — never let workers import concrete backends.
• kind discriminator is the extension point for new feature families. Adding kind="cmd_ngram" later does not require schema changes — the vec_<kind> table is created lazily on first insert.
• Credential.attacker_uuid is nullable on write by design — the credential capture path runs before the profiler mints Attacker, so coupling them would create a chicken-and-egg ordering bug. The profiler backfills.
• CredentialReuse.confidence is always 1.0 today (exact-secret match). The column exists so a future fuzzy-credential pass (hunter2 ≈ hunter22) can write 0.x rows without schema work.

Verification checklist for the next agent

After finishing each chunk:

• pytest tests/<area> --timeout=30 --timeout-method=thread — must be green before moving on.
• Don't run fuzz/bench/live/stress in the dev loop (memory: feedback_skip_heavy_tests).
• Don't pre-clear with custom bandit/ruff flags (memory: feedback_trust_git_hooks) — the pre-commit hook is authoritative.
• Commit per task, not batched (memory: feedback_commit_per_task). Don't add Co-Authored-By to commit messages.

Open questions to surface to ANTI before tackling §4

• Should the dashboard "Reuse" surface live as a tab on the existing Credentials page, or as a sibling page? (The plan said tab, but worth confirming once you've seen the code.)
• Pagination size for the reuse list — match the existing Credentials view default, or use a smaller page since the rows are wider?