VrtxOmega/veritas-opensearch-incident-proofpack

Investigate OpenSearch Incidents

Produce a replayable incident evidence packet without turning a plausible root-cause story into permission to act.

Requires Python 3.11+. OpenSearch access is optional for replay; live investigations require a reachable cluster or OpenSearch MCP server.

Critical rules

1. Discover the cluster, indices, mappings, time fields, and available observability plugins before writing a query. Never assume field names.
2. Run only read operations. This skill must not change cluster state, restart a service, delete data, acknowledge an alert, or execute a remediation.
3. Preserve support and refutation separately. Never average contradiction into one confidence score.
4. Treat sources sharing a correlation_group as one dependence group, not independent votes.
5. Verify every emitted query against the connected cluster. If no cluster is available, label it UNVERIFIED_TEMPLATE.
6. Keep raw credentials, authorization headers, cookies, full prompts, and unnecessary payload content out of case files and packets.
7. Finish every packet with execution_authorized: false.

Workflow

1. Establish the incident boundary

Record:

• exact claim under investigation;
• cluster identity or sanitized alias;
• inclusive UTC time window;
• assessment time;
• operator audience;
• proposed remediation preview, if any.

If the claim is vague, narrow it to one falsifiable causal statement.

2. Discover before querying

Use an available OpenSearch client or MCP server to list relevant indices and inspect mappings. Identify log, trace, alert, metric, and deployment sources. Read references/opensearch-workflow.md before generating PPL or Query DSL.

3. Collect two-sided evidence

For each source, record the exact query, sanitized result, retrieval time, staleness limit, polarity, and dependence group. Seek at least one credible falsifier rather than only confirming telemetry.

When a direct cluster connection is available, use the bounded read-only collector:

python scripts/read_opensearch.py \
  --endpoint https://opensearch.example \
  --mode search \
  --index 'logs-*' \
  --query query.json \
  --out response.json

Use --mode ppl for a verified PPL body. Remote endpoints require HTTPS. Credentials come only from OPENSEARCH_USERNAME and OPENSEARCH_PASSWORD, or OPENSEARCH_BEARER_TOKEN; never put them in the command, query file, or URL.

Normalize each saved response:

python scripts/normalize_opensearch.py \
  --source-id payment-errors \
  --kind logs \
  --polarity SUPPORTS \
  --correlation-group request-7b1 \
  --query query.json \
  --result response.json \
  --retrieved-at 2026-07-29T10:05:00Z \
  --stale-after-seconds 900 \
  --out source.json

4. Build the deterministic packet

Assemble the case using references/case-schema.md, then run:

python scripts/incident_proofpack.py build \
  --case incident-case.json \
  --out incident-proofpack.json

Interpret the four evidence states literally:

• SUPPORTED_ONLY: active support exists and no active refutation exists.
• REFUTED_ONLY: active refutation exists and no active support exists.
• CONFLICTED: active support and active refutation both exist.
• UNDETERMINED: neither active support nor active refutation exists.

SUPPORTED_ONLY still yields REVIEW_REQUIRED, never execution authority. Every other state yields BLOCK.

5. Verify before presenting

python scripts/incident_proofpack.py verify \
  --case incident-case.json \
  --packet incident-proofpack.json

Verification recomputes the complete canonical packet. A changed conclusion, removed source, swapped target, altered parameter, stale digest, or surplus field must fail.

6. Present the operator packet

Report:

• claim and exact time window;
• evidence state;
• active support and refutation groups;
• stale, invalid, or out-of-window sources;
• contradictions and unresolved gaps;
• exact remediation preview and digest;
• packet digest;
• explicit non-execution boundary.

Do not call the packet a security audit, proof of factual truth, incident closure, or authorization.

Hostile check

Use the bundled mutation runner before trusting a new case shape:

python scripts/incident_proofpack.py hostile-check \
  --case incident-case.json \
  --packet incident-proofpack.json

All mutations must be rejected or remain non-authorizing. Read references/threat-model.md for the attack model.