Skip to content

Getting Started

Krishnendu Bhattacherjee edited this page Nov 10, 2026 · 2 revisions

Getting Started

  • Python 3.14, the version used for the verified pinned environment.
  • Node.js satisfying the installed Vite requirement: ^20.19.0 || >=22.12.0, plus npm.
  • The commands below target Windows/PowerShell. Linux CI checks have also been exercised locally; see TASKS.md for their scope.
  • Cloud inference avoids running a local model. Hardware performance has not been benchmarked; the project targets a modest workstation.

5.2 Backend Setup

  1. Clone the repository:

    git clone https://github.com/KrishnenduOfficial/triagelens.git
    cd triagelens
  2. Create and activate a virtual environment (PowerShell):

    python -m venv .venv
    .\.venv\Scripts\Activate.ps1

    On a POSIX shell, activation is source .venv/bin/activate.

  3. Install dependencies:

    python -m pip install -r requirements.txt
  4. Configure environment variables:

    if (-not (Test-Path -LiteralPath .env)) {
        Copy-Item .env.example .env
    }

    Edit .env to configure your API keys and model parameters:

    GROQ_API_KEY=your_groq_api_key_here
    GROQ_MODEL=openai/gpt-oss-120b
    GROQ_FALLBACK_MODELS=
    DATABASE_PATH=data/triagelens.db
    VIRUSTOTAL_API_KEY=
    ABUSEIPDB_API_KEY=
    URLHAUS_API_KEY=

    Groq needs a real key for live triage. Intelligence credentials are optional: enter real values for services you use and leave unused credentials blank, including URLHAUS_API_KEY in the template. Example placeholder strings are treated as configured credentials; they are not working API keys. (Note: TRIAGELENS_DB_PATH is also recognized as an alias for DATABASE_PATH, and VT_API_KEY as an alias for VIRUSTOTAL_API_KEY).

    VIRUSTOTAL_MIN_DETECTIONS defaults to 3 malicious engine detections; set it to a positive integer to adjust the enrichment flag. A result below the threshold, including one or two detections, does not prove an indicator is safe. ENRICHMENT_WAIT_MODE defaults to false; set it to true to allow rate-limit waits bounded by ENRICHMENT_MAX_WAIT_SECONDS. ENRICHMENT_MAX_LOOKUPS_PER_RUN=0 is parsed as no cap, but the environment variable is currently unused by the runtime, even when set to a positive value. Use the CLI --max-lookups option to enforce a per-run lookup cap.

    CLI, API, and the evaluation runner share database resolution: explicit CLI override, nonblank DATABASE_PATH, nonblank TRIAGELENS_DB_PATH, then data/triagelens.db. Relative paths use the project root containing src/, regardless of the process working directory; absolute paths retain their target. Parent directories are created consistently. Blank explicit overrides and filesystem errors fail before SQLite opens. Windows drive-only/root-only paths must be replaced with fully qualified or ordinary project-relative paths. :memory: explicitly selects an ephemeral database local to each connection.

    --db-path affects only that CLI/evaluation invocation. Configure the API with the same target and restart it after changing configuration. Existing databases are not moved or merged. The historical root triagelens.db is separate from the default data/triagelens.db; to select it, use DATABASE_PATH=triagelens.db consistently for both processes. A genuinely empty selected database still produces zero metrics. See the path verification.

    The template also documents GROQ_REQUESTS_PER_MINUTE, GROQ_TOKENS_PER_MINUTE, GROQ_ESTIMATED_TOKENS_PER_REQUEST, GROQ_MAX_WAIT_SECONDS, DATABASE_BACKEND, YARA_SCAN_ROOTS, ALLOWED_ORIGINS and VITE_API_BASE_URL. See .env.example for defaults and optional PostgreSQL settings. Never commit real credentials.

    Troubleshooting: Missing Groq credentials prevent live triage; provider quotas and timeouts can yield unavailable results. An empty dashboard can indicate an empty database or a different API database path. Check the API health endpoint, the configured path and browser origin, then restart the API after configuration changes. A missing enrichment response is not a clean finding.


5.3 End-to-End Execution Sequence

Run these from the project root with the virtual environment active. Live CLI runs can contact both Groq and configured intelligence services and consume quota.

  1. Prepare a dedicated synthetic alert input folder:

    New-Item -ItemType Directory -Force data/raw/demo | Out-Null
    if (Test-Path -LiteralPath data/raw/demo/telemetry.json) { throw 'Demo input already exists; choose another directory or review it before replacing it.' }
    Copy-Item -LiteralPath data/synthetic_soc_telemetry.json -Destination data/raw/demo/telemetry.json

    data/raw/ is Git-ignored. Keep alert inputs separate from the benchmark JSON and databases; do not feed the entire mixed data/ directory into alert intake.

  2. Run the pipeline:

    python -m src.cli --data-dir data/raw/demo --db-path data/triagelens.db

    Save the Evaluation run: UUID and the final PIPELINE EXECUTION SUMMARY for the comparison below. A configured Groq key and completed triage outcomes are needed for a meaningful AI metric comparison; missing credentials skip triage. This command makes live requests and may consume quota; one run of this synthetic input produced 50 timelines, potentially requiring 50 triage requests before retries. Check your available quota before starting. To skip Groq while retaining enrichment:

    python -m src.cli --data-dir data/raw/demo --db-path data/triagelens.db --skip-llm

    --skip-llm is not an offline switch: intelligence lookups can still occur. Use the guarded test suite for offline verification.

  3. Check the database populated by that run:

    python -c "import sqlite3; c=sqlite3.connect('file:data/triagelens.db?mode=ro', uri=True); print('timelines:', c.execute('SELECT COUNT(*) FROM timelines').fetchone()[0], 'evaluations:', c.execute('SELECT COUNT(*) FROM evaluations').fetchone()[0]); c.close()"

    The read-only open fails if the file is missing. Existing rows can be from earlier runs; the Run selection below isolates this run. A zero evaluation count does not demonstrate populated AI metrics.

  4. Start the backend in a separate terminal, from the project root:

    .\.venv\Scripts\Activate.ps1
    $env:DATABASE_PATH = 'data/triagelens.db'
    python -m uvicorn src.api.main:app --host 127.0.0.1 --port 8000 --reload

    Configure the API's DATABASE_PATH to the same file as the CLI. Open http://127.0.0.1:8000/docs for the API or /api/metrics for stored metrics.

  5. Start the dashboard in another terminal, initially at the project root:

    cd dashboard
    npm ci
    npm run dev

    Open the local URL printed by Vite (normally http://localhost:5173). The default backend URL is http://localhost:8000. For a different backend, put the public URL in dashboard/.env.local before starting Vite:

    VITE_API_BASE_URL=http://127.0.0.1:8000

    Vite uses the dashboard directory for its environment files; setting this only in the root .env does not configure the frontend. Restart Vite after changes. Groq and intelligence secrets stay in the root .env, never in VITE_* values.


5.4 Manual Click-Through Verification Checklist

  • Open /health on the API and verify database connectivity.
  • Open http://127.0.0.1:8000/api/metrics?scope=run&run_id=<UUID>, replacing <UUID> with the CLI's Evaluation run: value. Compare tp, tn, fp, fn, total, unknown, abstained and unavailable with the CLI summary; compare applicable rates after converting API fractions to percentages.
  • On dashboard /, select Run under Scope, enter the same UUID in Run UUID, and click Apply selection. Verify the displayed Run ID, then compare confusion counts, binary-labeled results, unscored outcomes, undetermined dispositions, unavailable outcomes and applicable rates with the API and CLI. Default History includes earlier evaluations and need not match the latest run. N/A can be valid when a rate's denominator is zero; the CLI may print 0% instead. Check loading/error states; the UI does not certify live provider availability.
  • Use the timeline list on / and follow a row to /timeline/:id. Verify its alert details, intelligence and stored verdict. There is no /timelines page or incident-detail drawer in the current router.
  • On /hunt, try event_type == "ProcessCreate" or CommandLine contains "powershell". A valid query may return zero matching rows.
  • Check that failed triage is unavailable rather than a benign prediction and that historical model results remain distinguishable from new Groq results.
  • Record whether the same-run numbers match and share screenshots of the CLI summary and dashboard selection/results, with sensitive information removed. Do not claim this check passed until the operator confirms it on populated data.

Wiki home · Project README

Clone this wiki locally