Skip to content

SecOpsAI Findings Triage & Investigation Guide

A step-by-step guide for reviewing, investigating, and dispositioning SecOpsAI alerts.

Workflow

  1. Refresh and inspect findings:
cd /path/to/secopsai
source .venv/bin/activate
secopsai refresh
secopsai triage list --status open --limit 20
  1. Start analyst review:
secopsai triage start <FINDING_ID> --note "Initial analyst review started"
  1. Gather evidence and generate case files:
secopsai triage investigate <FINDING_ID> --json

Generated artifacts:

  • reports/triage/<finding_id>.json

  • reports/triage/<finding_id>.md

  • Close with analyst-confirmed disposition:

secopsai triage close <FINDING_ID> --disposition needs_review --note "Escalated to senior analyst"

Supported Dispositions

  • true_positive
  • false_positive
  • expected_behavior
  • accepted_risk
  • exception_granted
  • needs_review
  • tune_policy
  • remediated

Supply-Chain Triage

secopsai triage investigate SCM-XXXX automatically gathers:

  • finding summary and severity
  • package policy matches (allowlist / denylist)
  • local dependency references under the chosen search root
  • stored verdict explanation and matched rules
  • reputation signals from registry metadata when available
  • suggested disposition and next actions

Use it to quickly decide whether a package is:

  • true_positive
  • false_positive
  • expected_behavior
  • needs_review

False-Positive Relief

Immediate allowlist relief:

secopsai supply-chain allowlist add --ecosystem pypi --package textual
secopsai supply-chain explain-policy --ecosystem pypi --package textual
secopsai supply-chain reconcile-history --json
secopsai triage close SCM-XXXX --disposition false_positive --note "Verified legitimate package; added to allowlist."

Remove an allowlist entry:

secopsai supply-chain allowlist remove --ecosystem pypi --package textual

Tune a noisy rule instead of allowlisting a package:

secopsai supply-chain tune rule "wheel/sdist artifact divergence" --weight 1
secopsai supply-chain tune rule "manifest executable entrypoints" --disable

Tune thresholds:

secopsai supply-chain tune threshold --global-threshold --value 12
secopsai supply-chain tune threshold --ecosystem pypi --value 12
secopsai supply-chain tune threshold --package langchain --package-ecosystem pypi --value 14

Ask SecOpsAI to propose a threshold from reviewed history:

secopsai supply-chain suggest-threshold --ecosystem npm
secopsai supply-chain suggest-threshold --ecosystem pypi --package textual

Use allowlisting when one known-safe package keeps firing. Use rule or threshold tuning when the same heuristic is noisy across many legitimate packages.

Get a recommended false-positive action from a finding ID:

secopsai supply-chain suggest-fp-action SCM-XXXX --search-root /path/to/repo

This suggests one of:

  • close as expected_behavior
  • add the package to the allowlist
  • tune a noisy rule
  • keep the finding in needs_review

Guarded auto-close for clearly safe supply-chain false positives:

secopsai triage auto-close-safe-fp SCM-XXXX --search-root /path/to/repo

If the safe path requires an allowlist entry first, make that explicit:

secopsai triage auto-close-safe-fp SCM-XXXX --search-root /path/to/repo --allow-allowlist --reconcile-history

Host-Based Triage

secopsai triage investigate OCF-XXXX currently supports:

  • policy denial review
  • exfiltration review
  • generic host finding review with evidence summary and next actions

Best Practices

  • Always add a meaningful closure note.
  • Use triage start before deep analysis so the SOC store reflects active analyst review.
  • Treat triage investigate as evidence gathering, not auto-closure.
  • Keep the generated case files for audit trail and rule tuning.