Raven — Engineering Intelligence Agent

Raven is an open-source engineering intelligence agent. It learns a software project over time, detects architectural and security change, correlates it across revisions, and produces evidence-backed intelligence reports. Every report explains why something matters, not just what changed.

Evidence first. Engineering second. Opinion last.

Install

pip install .

Quick Start

raven init           # scaffold .raven directory
raven scan .         # run full analysis
raven score .        # compute risk score
raven report         # render existing artifacts
raven doctor         # environment sanity check
raven version        # show version info

SDK Usage

from ravenscan import scan, Raven
from raven.core.config import RavenConfig

profile = scan(".")
client = Raven(RavenConfig(path="."))

profile = client.scan()          # RepositoryProfile
arch = client.architecture()     # ArchitectureGraph
security = client.security()     # SecurityReport
risk = client.score()            # RiskScore
daily = client.daily_report()    # DailyReport

print(f"Score: {risk.overall}/100 — Grade {risk.grade}")

Output

All commands support --format json and --format markdown (default).

Artifacts are written to .raven/:

• RepositoryProfile.{json,md}
• ArchitectureGraph.{json,md}
• SecurityReport.{json,md}
• RiskScore.{json,md}
• DailyReport.{json,md}

JSON is canonical — Markdown is rendered from the JSON model, never independently.

Exit Codes (CI Integration)

raven score --fail-under 70   # CI gate: exit 1 if score < 70

WraithWall Connected Mode (remote)

Raven now supports connected mode with live WraithWall even from outside the server:

# anyone with a raven:use API key can use this before open source
raven wraith campaigns --api-key YOURKEY --api-secret YOURSECRET
raven wraith whoami --api-key ... --api-secret ...
raven wraith submit . --api-key ... --api-secret ...

• Defaults to https://wraithwall.online
• Public reads for campaigns/bgp (no key needed)
• Write/submit and whoami require key with raven:use scope (create in WraithWall UI)
• Works from laptop, CI, anywhere.

What Raven Is Not

Raven is a local CLI/SDK analyzer for repositories you point it at. It does not:

WraithWall vs Raven

To regenerate WraithWall publication diagrams from the validated corpus:

python3 scripts/generate_wraithwall_diagrams.py
# → static/img/architecture/*.svg + *.png

To deploy Cowrie without config-mount regressions:

chmod +x cowrie-analyzer/scripts/deploy-cowrie.sh
cowrie-analyzer/scripts/deploy-cowrie.sh

Development

pip install ".[all]"
pytest

License

MIT