SIFT(1)

NAME
sift - AI-powered alert triage summarizer for SOC teams

SYNOPSIS
sift COMMAND [OPTIONS] [ARGS]

sift triage [OPTIONS] FILE [FILE ...]

sift validate [OPTIONS] FILE [FILE ...]

sift doctor

sift metrics [OPTIONS] FILE

sift config [OPTIONS]

sift version

DESCRIPTION
sift ingests alerts from SIEM systems (JSON, Splunk JSON, CSV), deduplicates and clusters them by IOC overlap and time proximity, scores each cluster by risk, and produces a prioritized triage report.

AI-generated summaries are opt-in via --summarize. Core clustering is fully rule-based and works without any API keys. IOC enrichment via external APIs (VirusTotal, barb-phish) is opt-in and requires explicit consent.

sift reads configuration from ~/.sift/config.yaml and credentials from ~/.sift/.env. All settings can be managed with sift config.

COMMANDS

  triage
Process one or more alert files and produce a prioritized triage report. Multiple files and directories are supported; alerts are correlated across all sources before clustering.

sift triage [OPTIONS] FILE [FILE ...]

Arguments:

    FILE
        Alert file (JSON, Splunk JSON, CSV, NDJSON) or directory. Use - to read from stdin. Directories are scanned recursively for .json, .csv, .ndjson, and .log files.

Output options:

    -f, --format FMT
        Output format. One of rich (default), console, json, csv, stix.

    -o, --output PATH
        Save output to file. For rich format the terminal output is shown and a JSON copy is written to PATH.

    -q, --quiet
        Suppress the banner and status lines.

AI summarization options:

    -s, --summarize
        Generate a triage summary. Uses the configured LLM provider (default: template). The template provider requires no API key and produces a structured summary without AI. For AI-generated summaries use --provider anthropic or another LLM provider.

    --provider PROVIDER
        LLM provider for summarization. One of template (no key), anthropic, openai, ollama. Overrides the default set in config.yaml.

IOC enrichment options:

    --enrich MODE
        Enrich extracted IOCs. MODE is one of: local (heuristics only, no external API), barb (phishing URL analysis), vex (VirusTotal reputation), all (barb + vex; default when flag is used without MODE). External modes (barb, vex, all) require consent (see --yes).

    -y, --yes
        Skip the interactive consent prompt for external enrichment API calls.

Privacy options:

    --redact-fields FIELDS
        Comma-separated list of alert fields to redact before AI submission (e.g. user,host,source_ip). Overrides the default set in config.yaml.

Other options:

    --filter EXPR
        Filter clusters by expression (e.g. priority >= HIGH). Supports AND, OR, NOT, IN, NOT_IN and comparisons ==, !=, <, >, <=, >=.

    --no-cache
        Disable result caching for this run (cache is on by default).

    --help-all
        Show all options including expert flags (chunk-size, drop-raw, no-dedup, etc.).

Exit codes:

    0   No critical clusters found.

    1   One or more critical clusters found.

    2   Error (bad input, missing file, parse failure).

  validate
Parse and validate alert files without running the full pipeline. Reports the detected format and alert count for each file. Useful for testing ingestion pipelines and verifying file formats before triage.

sift validate [OPTIONS] FILE [FILE ...]

Exit codes: 0 = all files valid, 2 = one or more errors.

  doctor
Run diagnostic checks on the sift environment. Reports Python version, installed dependencies (anthropic, openai, barb, vex), LLM API key status, output directory, result cache, and module health.

sift doctor

Exit codes: 0 = all checks passed or warned (warnings indicate optional features), 1 = at least one check failed.

  metrics
Show statistics for alert files: cluster count, priority distribution, IOC type breakdown, and alert counts.

sift metrics [OPTIONS] FILE

    -q, --quiet
        Suppress the banner.

    --no-dedup
        Skip deduplication before computing metrics.

  config
Show or update persistent configuration. Settings are written to ~/.sift/config.yaml. The LLM API key is stored separately in ~/.sift/.env (mode 600) and never written to config.yaml.

sift config [OPTIONS]

Credential options:

    --api-key KEY
        Set the LLM API key (stored as SIFT_LLM_KEY in ~/.sift/.env).

    --unset-api-key
        Remove the LLM API key from ~/.sift/.env.

Summarization defaults:

    --provider PROVIDER
        Default LLM provider: template, anthropic, openai, ollama.

    --model MODEL
        Default LLM model name (e.g. claude-opus-4-6).

Output defaults:

    --quiet/--no-quiet
        Enable or disable quiet mode by default.

    --default-format FMT
        Default output format for sift triage (rich, console, json, csv, stix).

Pipeline defaults:

    --chunk-size N
        Default clustering chunk size (0 = auto-tune).

    --cache/--no-cache
        Enable or disable result caching by default.

    --enrich-consent/--no-enrich-consent
        Pre-approve consent for external enrichment API calls.

    --redact-fields FIELDS
        Default fields to redact before AI submission (comma-separated). Use an empty string to clear.

    --show
        Print the current configuration as YAML.

  version
Print the installed sift version and exit.

EXAMPLES

Triage a single alert file with rich terminal output:
    sift triage alerts.json

Triage multiple sources and correlate across them:
    sift triage firewall.json endpoint.csv siem/

Read from stdin (pipe from another tool):
    cat alerts.json | sift triage -

Generate a JSON report and save to file:
    sift triage alerts.json -f json -o report.json

Generate an AI triage summary using Anthropic:
    sift triage alerts.json --summarize --provider anthropic

Enrich IOCs with local heuristics (no external API):
    sift triage alerts.json --enrich local

Enrich with VirusTotal and barb-phish (requires consent):
    sift triage alerts.json --enrich all --yes

Redact sensitive fields before AI submission:
    sift triage alerts.json --summarize --redact-fields user,host,source_ip

Filter output to high-priority clusters only:
    sift triage alerts.json --filter priority >= HIGH

Export a STIX 2.1 bundle:
    sift triage alerts.json -f stix -o bundle.json

Validate files before triage:
    sift validate alerts.json splunk.json siem/

Configure Anthropic as the default provider:
    sift config --api-key sk-ant-... --provider anthropic

Set default redact fields and quiet mode:
    sift config --redact-fields user,host --quiet

Show all expert flags:
    sift triage --help-all

Run diagnostics:
    sift doctor

FILES

~/.sift/config.yaml
    Persistent user configuration. Created automatically on first use. Managed by sift config.

~/.sift/.env
    LLM API key storage (mode 600). Written by sift config --api-key. Contains SIFT_LLM_KEY=<key> and is never included in config.yaml.

~/.sift/cache.db
    SQLite result cache (WAL mode). Stores triage results with a 1-hour TTL. Cache is on by default; disable per-run with --no-cache.

~/.sift/version_check.json
    Stores the last PyPI version check timestamp to avoid repeated network calls.

ENVIRONMENT

SIFT_LLM_KEY
    LLM API key. Equivalent to setting it with sift config --api-key. When both SIFT_LLM_KEY and ~/.sift/.env are present the environment variable takes precedence.

INPUT FORMATS
sift auto-detects the input format:

Generic JSON
    Array of alert objects with arbitrary field names. Field mapping is inferred from common naming patterns (title, description, severity, src_ip, dst_ip, etc.).

Splunk JSON
    Output of Splunk search commands (results key with per-event fields).

CSV Comma-separated values with a header row.

NDJSON / .log
    Newline-delimited JSON; one alert object per line.

OUTPUT FORMATS

rich
    Colored terminal table with cluster cards, IOC lists, and priority badges (default).

console
    Plain-text terminal output without Rich markup.

json
    Full-fidelity JSON export of the triage report.

csv Flat per-alert CSV with cluster and priority columns.

stix
    STIX 2.1 bundle containing threat indicator objects for each cluster.

PIPELINE
Alerts are processed in the following order:

    Ingest → Normalize → Deduplicate → Extract IOCs → Cluster → Prioritize → Enrich (opt) → Summarize (opt) → Output

For large inputs (>50 MB) the ingestion stage streams line-by-line to avoid loading the entire file into memory. Files larger than 500 MB are processed in batches of 100,000 alerts (sub-file chunking).

EXIT CODES

0   Success. For sift triage this means no critical clusters were found.

1   sift triage: one or more clusters with CRITICAL priority were found. sift doctor: at least one diagnostic check failed.

2   Error — bad input, missing file, parse failure, or invalid flag value.

SEE ALSO
jq(1), grep(1)

Project homepage and documentation: https://github.com/duathron/sift

PyPI package: https://pypi.org/project/sift-triage/

AUTHOR
Christian Huhn <https://github.com/duathron>