KRAVEN

KRAVEN is a terminal-based cybersecurity agent for dependency risk assessment and controlled remediation. It scans a target project, correlates package versions against OSV intelligence, uses Gemini 2.5 Flash to turn raw findings into an actionable security brief, and only executes remediation after explicit operator approval.

The project is designed for a mature workflow: inspect first, explain clearly, patch cautiously, and verify the outcome.

---

Operational Profile

KRAVEN is built around four core stages:

• discovery of package and dependency exposure
• structured vulnerability analysis
• operator review and approval
• constrained remediation with post-patch verification

This makes it useful as a local triage tool, a security review assistant, or a controlled patching front end for engineering teams that want more context than a basic scanner provides.

---

Capability Summary

Domain	Function
Scan path	Uses osv-scanner when available; falls back to the OSV API when needed
Analysis	Produces a concise AI-assisted security report with Gemini 2.5 Flash
User interface	Rich-based CLI with clear phases, tables, and approval prompts
Remediation	Generates package-manager patch plans only
Safety controls	Requires approval before execution and blocks unsafe shell behavior
Validation	Re-runs the scan flow after patch execution

---

Workflow

flowchart LR
    A["Target Folder"] --> B["Scan"]
    B --> C["Analyze"]
    C --> D["Report"]
    D --> E{"Operator approval"}
    E -- "Decline" --> G["Summarize"]
    E -- "Approve" --> F["Patch"]
    F --> H["Verify"]
    H --> G["Summarize"]

Loading

Execution Model

1. The operator selects a folder.
2. KRAVEN identifies dependency versions using osv-scanner or supported fallback sources.
3. Vulnerability data is normalized into a structured internal state.
4. Gemini generates a security report focused on risk, fixability, and next action.
5. KRAVEN requests explicit approval before producing or executing a patch plan.
6. If approved, KRAVEN runs validated package-manager commands only.
7. KRAVEN performs a verification pass and summarizes remaining exposure.

---

Scan Sources

KRAVEN supports two scanning modes.

Primary Mode

• osv-scanner binary, when installed and reachable through PATH or OSV_SCANNER_PATH

Fallback Mode

Used when the binary is unavailable.

Current fallback sources include:

• requirements*.txt entries pinned with ==
• package-lock.json
• Python virtual environments such as .venv, using installed versions from pip list

This fallback mode is designed to preserve usability, but the most complete ecosystem coverage still comes from the native osv-scanner binary.

---

Safety Controls

KRAVEN is intentionally restrictive when moving from analysis to action.

• no remediation runs without explicit user approval
• no arbitrary shell chaining
• no redirects, pipes, or command composition tricks
• no curl, wget, rm, del, or privilege-escalation paths
• no execution outside the selected project directory
• only package-manager style commands are allowed during patch execution

These controls are deliberate. The objective is to assist remediation without turning the tool into an unrestricted autonomous shell.

---

Interface

The CLI is built with Rich and organized to feel more like an operator console than a generic script.

+--------------------------------------------------------------------+
|                               KRAVEN                               |
|            Autonomous Cybersecurity Intelligence Agent             |
|                Gemini 2.5 Flash | LangGraph | OSV                 |
+--------------------------------------------------------------------+

   SCAN                 ANALYZE                 PATCH
   OSV Scanner/API      Gemini 2.5 Flash       Approval gated

The interface emphasizes:

• phase separation
• readable risk tables
• explicit approval prompts
• visible patch plans before execution
• clear terminal summaries at the end of each run

---

Setup

Runtime

A working local Python 3.11 environment is initialized in .venv311.

Run KRAVEN with:

.\.venv311\Scripts\python.exe kraven.py

Environment Variables

Configure Gemini in .env:

GEMINI_API_KEY=your_key_here

Optional scanner override:

OSV_SCANNER_PATH=C:\path\to\osv-scanner.exe

Reinstall Dependencies

py -3.11 -m pip --python .\.venv311\Scripts\python.exe install -r requirements.txt

Reference documentation:

• OSV-Scanner installation
• OSV API quickstart

---

Usage

Interactive Mode

.\.venv311\Scripts\python.exe kraven.py

Direct Target Mode

.\.venv311\Scripts\python.exe kraven.py C:\path\to\project

---

Repository Layout

File	Purpose
kraven.py	Main CLI application and LangGraph workflow
.env	Runtime secrets and optional scanner path override
requirements.txt	Python dependencies
CODEX_PROMPT.md	Codex-oriented project brief
README.md	Project documentation

---

Intended Use

KRAVEN is best suited for:

• local dependency exposure reviews
• security-assisted upgrade planning
• human-in-the-loop remediation sessions
• engineering teams that want narrative context around vulnerability data

It is not a replacement for a full enterprise vulnerability management platform, and it does not attempt arbitrary exploit remediation beyond dependency and package-level upgrade paths.

---

Roadmap

High-value next steps include:

• support for additional lockfile formats such as poetry.lock and Pipfile.lock
• persistent scan artifacts and report export
• severity and ecosystem filtering before patch generation
• richer verification diff output between pre- and post-patch states

---

Notes

• Fallback quality depends on the dependency metadata available in the target project.
• When available, osv-scanner remains the preferred source for broader and more reliable ecosystem coverage.
• Automatic patching should still be treated as an assisted operation, not an unreviewed background action.