Skip to content

Research Cases

SecOpsAI Research Cases turn discovery leads, package analysis, SOC findings, and public-source evidence into a durable investigation record. Cases are local-first and stored in the Core SQLite SOC database.

Ownership Boundary

  • Supply-chain discovery and scanners produce leads and technical evidence.
  • Research Cases own analyst workflow, provenance, disclosure, and publication readiness.
  • Core findings can be linked to a case without changing their triage state.
  • Blog Ops receives review-only drafts. It never publishes directly from a research case.

Calibrated Assessments

Case prioritization, detection confidence, maliciousness assessment, potential impact, and local exposure are separate fields. A critical-looking source heuristic is not a critical verdict. Read the case decision card first, then inspect unique observations, path context, reachability, and evidence quality. Legacy cases can be repaired without deleting history:

secopsai research case reconcile RSC-... \
  --actor artifact-signal-calibrator --json

The command reconciles subject state with the artifact catalog, reclassifies source/documentation URLs, and records an audit event for every change. See Artifact Signal Calibration.

Case Lifecycle

Statuses are:

draft → investigating → validation → disclosure_pending → ready_to_publish → published or closed.

Disclosure is tracked separately as not_started, not_required, preparing, reported, coordinating, disclosed, or closed.

Every mutation appends an immutable case event. Subjects, evidence, IOCs, and finding links remain structured instead of being hidden in a prose report.

Incorrect structured records are retracted, not deleted:

secopsai research case retract RSC-... \
  --item-type evidence \
  --item-id EVD-... \
  --reason "Registry record belonged to a different namespace"

Retractions require a reason, remain visible in the case history, and are excluded from readiness, exports, and publication. An active IOC linked to retracted evidence blocks publication until its provenance is corrected.

Execution-Grounded Reliability

Material research cases expose one reliability workspace rather than separate ecosystem-specific workflows. Generate and rank competing hypotheses, create a versioned evidence plan, pass scaffold and transition gates, run full safe research, and inspect the tamper-evident bundle before drafting. The claim ledger then verifies every factual sentence against case evidence. Unsupported or contradicted claims are removed or qualified with a revision diff.

The domain specialist and blinded independent reviewer run in separate contexts. A material disagreement is a publication blocker until an operator records accept_primary, accept_reviewer, or request_more_evidence with an evidence-backed rationale. Completeness, originality, visual QA, and publication safety remain independent gates. See Research Reliability Operations and Research Review And Adjudication.

Detection Rules

Research cases can carry defensive YARA, Sigma, and Semgrep artifacts. Rules are stored as text with their purpose, source evidence, structural validation result, and case timeline event. SecOpsAI never executes a submitted rule. Sigma and Semgrep documents are parsed with safe YAML loading; YARA receives a bounded structural preflight (declaration, braces, and condition) rather than claiming compiler-level validation.

The recommended path is the guarded proposal workflow:

secopsai research rule propose RSC-...
secopsai research rule list RSC-...
secopsai research rule review RSC-... RRP-... --decision accepted

Proposal generation is deterministic and evidence-bound. It can create:

  • exact-artifact YARA rules from reviewed suspect package hashes;
  • Sigma network rules from high-confidence domain or IP IOCs;
  • Semgrep source indicators from high-confidence domains or URLs.

Legitimate comparison artifacts, low-confidence indicators, unlinked model claims, and raw package content are excluded. Generation never activates a rule. A proposal must pass structural and policy validation and then receive an explicit accept decision. Rejected and failed proposals remain in the audit history. The model may explain limitations, but it is not evidence and does not control activation.

Attach a rule from inline content or a local UTF-8 file:

secopsai research case add-rule RSC-... \
  --rule-type sigma \
  --name suspicious-package-execution \
  --file ./rules/suspicious-package.yml \
  --purpose "Detect process execution associated with package installation." \
  --source-evidence-id EVD-...

Each active rule must pass structural validation before a case can become publication-ready. Failed rules remain visible for analyst review and can be replaced idempotently by repeating the same case, type, and name. Retract a replaced rule without deleting its history:

secopsai research case retract RSC-... \
  --item-type rule \
  --item-id RUL-... \
  --reason "Replaced with the reviewed production rule"

Case JSON and Markdown exports include active rule content and validation status, making published detections reproducible alongside the research evidence. Rules are optional for publication; when present, every active rule must pass the structural gate.

Create And Build A Case

Automated source-first package and artifact research

The canonical adapter-driven workflow can collect an exact package or approved artifact, verify metadata and checksums where available, quarantine and statically inspect the archive, compare an explicitly supplied reference, and create or reuse a case:

secopsai research investigate \
  --ecosystem crates \
  --research-type package_compromise \
  --package proc-macro1 \
  --version 1.0.107 \
  --comparison-package proc-macro2 \
  --comparison-version 1.0.107 \
  --persist-findings --json

Replace crates with any supported ecosystem and select the research type that matches the question. The workflow records execution_performed=false and does not install, activate, or run package code. Strong deterministic findings can enter the SOC queue and model review, but the case remains subject to evidence, disclosure, publication, and deployment gates. See Universal Source-First Security Research.

For a fast, safe package-research start, use the guided command. It records a package subject and optional analyst-supplied source URL. It does not fetch a registry or execute anything. With --artifact, it reads the local regular file only to calculate a SHA-256 hash; it does not unpack or retain the file.

secopsai research case start-package \
  --ecosystem nuget \
  --package Braintree.Payments.SDK \
  --version 4.2.1 \
  --source-url https://example.com/package \
  --artifact ./fixtures/package.nupkg \
  --owner "SecOpsAI Research"

The resulting case starts in draft with explicit validation language. Add evidence, IOCs, findings, and disclosure updates as the investigation earns them. To attach a local artifact to an existing case:

secopsai research case add-artifact RSC-... \
  --artifact ./fixtures/package.nupkg \
  --notes "Hash-only collection from the isolated evidence directory"

Promote A Watchlist Lead

The first automated watchlist workflow is intentionally narrow: it supports explicitly selected npm package leads from the local campaign watchlist. The default is a read-only preview. It does not query a registry, download an artifact, unpack a package, or execute package code.

Preview one lead:

secopsai research case from-watchlist \
  --ecosystem npm \
  --package npm:chalk-tempalte \
  --watchlist-path data/supply_chain/campaign_discovery/watchlist.json

Create the case only after reviewing the preview:

secopsai research case from-watchlist \
  --ecosystem npm \
  --package npm:chalk-tempalte \
  --owner "SecOpsAI Research" \
  --create

Promotion is idempotent for an active npm package subject, records local watchlist provenance, and leaves the case in draft with validation open. Use --all --create only after reviewing the complete npm watchlist. Other ecosystems are rejected by this first workflow rather than being silently treated as npm packages. Add public source URLs later with the evidence workflow; the promotion command never fetches them.

secopsai research case create \
  --title "NuGet payment SDK typosquat investigation" \
  --type typosquatting \
  --severity critical \
  --confidence 80 \
  --owner "SecOpsAI Research" \
  --summary "A suspicious package copied legitimate branding and introduced attacker-controlled checkout telemetry."

secopsai research case add-subject RSC-... \
  --subject-type package \
  --ecosystem nuget \
  --name Braintree.Payments.SDK \
  --version 4.2.1

secopsai research case add-evidence RSC-... \
  --evidence-type source \
  --title "Public registry package record" \
  --locator https://example.com/package \
  --provenance "public package registry"

secopsai research case add-ioc RSC-... \
  --ioc-type domain \
  --value checkout-telemetry.example \
  --confidence 90

secopsai research case link-finding RSC-... SCM-... --relationship derived_from

Use secopsai research case list and secopsai research case show RSC-... to inspect the queue and full timeline.

Publication Readiness

A case cannot create a blog draft until all deterministic gates pass:

  • clear title and substantial executive summary
  • at least one structured subject
  • at least two evidence records
  • at least one public source or registry record with a locator
  • confidence of 60 or greater
  • disclosure completed or explicitly marked not required
  • case status set to ready_to_publish
  • every attached active detection rule passes structural validation

Missing IOCs or linked findings are warnings, not automatic blockers, because a valid investigation may produce no attacker infrastructure or local exposure.

secopsai research case update RSC-... \
  --status ready_to_publish \
  --disclosure-status disclosed \
  --confidence 90

secopsai research case export RSC-...
secopsai research case draft-blog RSC-...

Exports are deterministic JSON and Markdown under reports/research/cases/. Each export also includes a .manifest.json with byte counts and SHA-256 checksums for the JSON and Markdown files. The export schema is secopsai.research.case.v1; the manifest schema is secopsai.research.export-manifest.v1. Re-exporting an unchanged case produces the same report bytes, which makes review, archival, and publication checks reproducible. Draft handoff produces an Original Research Blog Ops item with review_status=needs_review; editorial approval and deployment remain separate actions.

Dashboard

Open Research in the canonical SecOpsAI dashboard to:

  • review the case queue and publication blockers
  • manage status, severity, confidence, owner, and disclosure
  • add subjects, evidence, IOCs, notes, and finding links
  • generate evidence-linked rule proposals, review their validation limits, and activate or reject them
  • review active case-linked detection rules and their validation status
  • download a Markdown case report
  • create a review-only blog draft when readiness passes

Reads do not require a write token. Protected actions use the same TRIAGE_OPS_ADMIN_TOKEN boundary as Triage Ops. The token stays in browser session storage and is forwarded only to the authenticated helper.

Safety And Ethics

  • Collect public metadata and artifacts or data you are authorized to inspect.
  • Prefer static analysis in isolated directories.
  • Run dynamic analysis only in disposable, network-controlled sandboxes.
  • Never execute untrusted packages on the operator workstation.
  • Record provenance, hashes, timestamps, and limitations.
  • Coordinate with affected vendors, registries, and maintainers before public disclosure when publication could increase harm.
  • Do not include live credentials, private victim data, or unnecessary personal information in evidence or reports.

Structured cryptographic hash IOCs are preserved in public drafts. Unstructured secret-like values remain redacted.