# Logical Architecture Guide

This guide explains how RAVENSTRIKE conceptually routes and processes threat detection tasks through its multi-stage pipeline.

---

## Conceptual Ingest-to-Package Workflow

RAVENSTRIKE is designed around an explicit pipeline. When you input a threat scenario or alert description, the agent routes and enriches that input, ultimately generating detection logic and packing it for triage.

```text
Analyst Input ➔ Intent Router ➔ Ingest ➔ Scope ➔ Enrich ➔ Detect ➔ Cover ➔ Triage ➔ Package
```

### The 7 Pipeline Stages

#### 1. Ingest
* **What it does**: Establishes the entry point for raw analyst logs, command strings, or descriptions. It stamps timestamps and tracks input types (slash commands vs. free-form text).

#### 2. Scope
* **What it does**: Identifies the primary MITRE ATT&CK target technique, clarifies what telemetry sources are required to investigate the behavior, and outlines immediate blind spots.

#### 3. Enrich
* **What it does**: Normalized fields mapping (e.g. mapping raw logs to a standardized layout) and calculates a security priority rating (e.g., P1, P2) for incident response.

#### 4. Detect
* **What it does**: Generates the concrete detection rule logic. It constructs a **portable Sigma rule** (with false-positive filters and metadata) and a **native platform query** matching the targeted platform (e.g., KQL for Sentinel, SPL for Splunk).

#### 5. Cover
* **What it does**: Maps current ATT&CK technique coverage and lists prioritize-gap detection recommendations (highlighting what related techniques are missing rules).

#### 6. Triage
* **What it does**: Generates a brief summary, a checklist of investigative evidence for analysts, and instructions on how to proceed if the alert is a true vs. false positive.

#### 7. Package
* **What it does**: Merges all preceding stages into a unified, SOAR-ready JSON incident package containing the incident ID, threat mappings, evidence summary, and playbook recommendations.

---

## Operating Assumptions & Guardrails

* **Verification Priority**: All generated Sigma rules and platform queries require manual validation before implementation. They are templates, not production changes.
* **Platform Translation Only**: Selecting platform profiles (like CrowdStrike or QRadar) selects corresponding query formatting templates. It does **not** connect to or search live SIEM databases.
* **Rarity Context**: The system uses process-local frequency tracking to calculate input rarity context. If an analyst runs the same input multiple times, the system learns the input and lowers its rarity score.
* **Safety Error Shielding**: If a pipeline stage fails validation or encounters an error, the pipeline will automatically generate a fallback telemetry envelope rather than crashing, letting you continue triage.