Case Management

Case Management

Case management was introduced in v0.3.0 and hardened in v0.3.1. A case is a private, versioned, resumable workspace that records authorization and preserves execution provenance. Subsequent releases add normalized reporting, entity projections, deterministic workflows, evidence integrity and portable bundles, and—at stable v0.8—provider evidence plus a deterministic intelligence graph without replacing existing case records.

Create a case

osint case create example-case \
  --purpose "Investigate authorized brand impersonation" \
  --authorization "Written authorization from Example Organization"

Case IDs are validated and cannot traverse the case root. Purpose and authorization are required.

Add seed targets

All stable target types remain supported, including name, phone, and address seeds:

osint case add example-case username example_handle
osint case add example-case email analyst@example.com
osint case add example-case phone '+1 202 555 0100'
osint case add example-case name 'Example Person'
osint case add example-case address '100 Example Street, Example City'
osint case add example-case domain example.com
osint case add example-case ip 192.0.2.10
osint case add example-case image ./photo.jpg
osint case add example-case file ./evidence.bin

Targets are validated, normalized, and deduplicated. File and image targets must exist and are stored as normalized paths.

Inspect entities

The canonical, provenance-aware entity projection now includes both explicit seeds and extracted candidates:

osint case entities example-case
osint case entities example-case --json

A seed and one or more extracted observations can project to one canonical entity while retaining every source reference. Candidate entities remain observations—not verified relationships, identity conclusions, or automatic follow-up instructions. Stable v0.8 adds a separate provider intelligence graph with inspectable evidence-backed relationships and confidence assessments; bounded recursive pursuit remains scheduled for v0.9.

Provider evidence and intelligence

osint case search example-case ./provider-adapter.json
osint case observe example-case example-search ./provider-results.json
osint case intelligence example-case
osint case intelligence example-case --json

search executes an explicitly selected, versioned argv adapter against compatible case seeds. observe strictly validates and preserves externally obtained provider JSON without executing the named provider. intelligence derives a deterministic, provenance-linked graph containing observations, canonical entities, evidence-backed relationships, contradictions, verification status, temporal status, and separate observation, relationship, identity, and currentness confidence. Provider evidence is the primary discovery layer; plugins remain conditional verification and enrichment sensors. No v0.8 command recursively pursues discoveries.

Preview, run, and resume

osint case run example-case --plugins maigret sherlock --dry-run
osint case run example-case --plugins maigret sherlock --jobs 2
osint case status example-case
osint case status example-case --json

A normal rerun skips successful jobs and retries failed or missing jobs. Interrupted work records an interrupted state and remains resumable. Use --rerun only when successful jobs should execute again. Dry-runs preserve planned provenance but do not mark jobs successful.

Reports and findings

osint case report example-case
osint case report example-case --format json
osint case report example-case --format all
osint case findings example-case
osint case findings example-case --json

The default Markdown report is report.md. The --format option accepts markdown, json, html, csv, or all; the default additional files are report.json, report.html, and findings.csv. Reports retain completed, failed, and previewed outcomes, normalization errors, stable finding IDs, and exact links to preserved evidence. A normalization failure remains visible and causes a nonzero exit after available reports are written.

A custom output path is available when generating one format. Existing custom files require --force, and reports cannot overwrite case metadata, activity logs, run records, raw evidence, reviews, or other reserved artifacts.

Analyst review

osint case annotate example-case FINDING_ID --confidence high
osint case annotate example-case FINDING_ID --note "Confirmed against an operator-owned profile."
osint case annotate example-case FINDING_ID --clear-note

Confidence values are unverified, low, medium, and high. Reviews live in findings/reviews.json, remain separate from raw output, and are retained as orphaned reviews if their finding disappears. Confidence is an analyst assessment; it does not transform automated output into verified fact.

Shareable reports

osint case report example-case --format all --shareable

This produces conservatively redacted Markdown, JSON, HTML, and CSV artifacts. The structure-only policy removes case purpose and authorization, original identifiers, targets, commands, paths, finding values and attributes, notes, and detailed errors. Human review before distribution remains mandatory. See Reporting for the complete contract and output filenames.

Case contents and privacy

Cases default to ~/OSINT-Cases/<case-id>/ and preserve versioned metadata, authorization, targets, entities, framework and plugin versions, commands, timestamps, status, raw output, reports, and append-only activity. Framework-created case directories are mode 700 and files mode 600.

Toward v1.0

The delivered path through v0.8 includes entity-aware adapters, deterministic planning, evidence integrity, portable bundles, provider ingestion, and explainable correlation and confidence. The remaining committed path adds controlled recursive discovery in v0.9 and the stable confidence- and currentness-filtered intelligence workflow in v1.0. Recursion will be opt-in and constrained by authorization scope, entity eligibility, depth, request and time budgets, loop prevention, and a complete audit trail. See Roadmap and Security and Ethics.

Guided case management at v1.0

The v1.0 guided interface must make the complete case lifecycle accessible without manual file editing or memorized commands:

• Create, open, select from recent cases, resume, and recover
• Add validated starting information one question at a time
• Review, edit, remove, deduplicate, and bulk-import seeds
• Record and revise purpose and authorization scope
• Plan and run an investigation with conservative bounded defaults
• Monitor recursive work and safely pause, resume, stop, or recover
• Resolve ambiguous matches by accepting, rejecting, or deferring
• Review findings and evidence, then generate the final report
• Save or exit safely from every appropriate screen

The advanced osint case ... commands remain available and operate on the same case model and application services. See Interactive UI.