# RAVENSTRIKE

RAVENSTRIKE is a production-ready, dynamic detection-engineering agent for SOC teams. It integrates seamlessly with AI assistants via MCP, ingests custom RAG context, and translates natural language threat descriptions into high-quality Sigma rules, target SIEM queries, and structured triage playbooks.

Analyst teams use RAVENSTRIKE via a terminal dashboard or a command-line interface (CLI) to draft, enrich, and package detections in seconds.

> [!IMPORTANT]
> RAVENSTRIKE is designed for rapid drafting, evaluation, and learning. Generated logic must be validated by an analyst before deploying to production SIEM, EDR, or SOAR environments. Live database querying and direct auto-deployments are not supported out-of-the-box.

---

## Capabilities & Implementation Status

| Operational Stage / Capability | Description | Status |
| --- | --- | --- |
| **Interactive Terminal Dashboard** | Text UI for running scenarios and seeing routes | Implemented |
| **Slash-command Router** | Quick commands like `/sigma` or `/triage` to target stages | Implemented |
| **Ingest-to-Package Workflow** | Full 7-stage enrichment and rules drafting pipeline | Implemented (encoded PowerShell reference scenario) |
| **Sigma & Query Generation** | Parallel Sigma rule and native platform query output | Implemented |
| **Output Schema Validation** | Enforces structured JSON outputs before returning | Implemented |
| **OpenAI AI Generation Integration** | Dynamic rule drafting using OpenAI models | Implemented (optional adapter) |

---

## Quick Start (For End Users)

RAVENSTRIKE requires **Node.js (v20+)** installed on your system.

### Option A: Zero-Install Quick Run (via `npx`)
Run RAVENSTRIKE instantly without installing any files permanently:

```bash
# Start the interactive Terminal Dashboard
npx @ravenstrike/agent dashboard

# Run the pipeline for a scenario on a specific platform
npx @ravenstrike/agent run --input "encoded PowerShell execution" --platform CrowdStrike
```

### Option B: Global System Install (via `npm`)
Install the tool globally to use the `ravenstrike` CLI command anywhere:

```bash
# Install globally
npm install --global @ravenstrike/agent

# Auto-install the MCP server into AI assistants (like Claude Desktop)
ravenstrike init-workspace

# Launch the interactive terminal dashboard
ravenstrike dashboard

# Run a CLI pipeline drafting task
ravenstrike run --input "run full pipeline for encoded PowerShell" --platform QRadar
```

---

## Supported Query Formats (Platforms)

Set your target platform label using the `--platform` CLI flag or by selecting it in the dashboard. Supported templates:
* `QRadar` (AQL)
* `CrowdStrike` (LSQL/LEQL)
* `Sentinel` (KQL)
* `Elastic` (EQL/KQL)
* `Splunk` (SPL)
* `Generic` (Platform-neutral)

---

## Core Document Guides

* **User Guides**:
  * [End-User Setup & Installation Guide](docs/setup.md)
  * [Logical Architecture Guide](docs/architecture.md)
  * [CLI & Dashboard Usage Guide](docs/usage.md)
* **Threat Hunter References**:
  * [System Prompt Logic & Instructions](docs/reference/system-prompt.md)
  * [Runtime Pipeline Specification](docs/reference/runtime-spec.md)

---

## For Developers & Code Adaptors

If you want to clone this repository, run local tests, extend the LLM adapters, or build custom detection modules, see the developer-focused documentation:

* **Guides for Adapting Code**:
  * [Developer Setup & Testing Guide](docs/developer/setup.md) (covers git cloning, `npm ci`, running unit tests, and validation scripts)
  * [Developer Architecture Guide](docs/developer/architecture.md) (covers codebase file mapping, orchestrator state machine, schemas, and LLM adapter boundaries)
  * [First Public Upload with GitHub Desktop](docs/developer/github-desktop.md)
  * [npm Release & Publishing Guide](docs/developer/publishing.md)
* **Developer Guidelines & Rules**:
  * [Contributing Guidelines](CONTRIBUTING.md)
  * [Code of Conduct](CODE_OF_CONDUCT.md)
  * [Security & Vulnerability Reporting Policy](SECURITY.md)

---

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.