Ventra

Cloud forensic triage: collect, normalize, investigate.

Ventra is a read only cloud incident response toolkit. A collector runs in the client's cloud environment (AWS CloudShell, Azure Cloud Shell, GCP Cloud Shell, or an IR workstation), gathers incident relevant logs and artifacts, seals them into a hashed evidence package, and hands off to an offline analyst console. No ongoing access to the client account is required after collection.

Architecture · Evidence Package Format · Operator runbook · Analyst runbook

Quickstart

Ventra needs Python 3.11+. The fastest path is uv (curl -LsSf https://astral.sh/uv/install.sh | sh, or brew install uv), which also fetches a suitable Python for you.

1. Try it instantly — no install

uvx ventra --help
uvx ventra collect aws --list-collectors
uvx ventra collect aws --case CASE-2026-0042 --since 2026-05-01 --out ./ventra-evidence

2. Install it permanently

uv tool install ventra
ventra --version
uv tool upgrade ventra        # after a new release

3. Fallback: pipx or pip

pipx install ventra
# or, inside a virtualenv you manage yourself:
python -m pip install ventra

The default install includes the AWS, Azure, GCP, and Kubernetes collectors and the analyst console, so every ventra subcommand works out of the box. Before running a collection, review the read only policy for your cloud in docs/iam-policies/.

About Ventra

Ventra streamlines collection of the data IR teams need during a cloud investigation. It is built for bounded, time scoped triage: not a SIEM replacement and not a live monitoring platform.

The workflow has three tiers, connected by a single contract: the Evidence Package Format (EPF).

┌────────────────┐   sealed .tar.zst   ┌────────────────┐         ┌────────────────┐
│   COLLECTOR    │  ────────────────►  │   INGESTER     │  ────►  │    CONSOLE     │
│  cloud shell   │   manifest + hash   │  parse/normalize│  query │   analyst GUI  │
│  read only IAM │                     │  verify/load    │         │  RBAC, offline │
└────────────────┘                     └────────────────┘         └────────────────┘

Every artifact is SHA 256 hashed at acquisition. Disabled, empty, or denied log sources are recorded in the manifest as gaps: missing telemetry is treated as evidence. After collection, analysis happens entirely on evidence copies; the console makes no outbound network calls and ships no telemetry.

Artifacts are declared in YAML; collectors execute in Python under a shared engine. The Acquire tab in the console lets an IR lead browse the catalog, preview narrowed IAM, choose a deployment profile, and download an operator kit without using the CLI.

Supported data sources

Ventra ships 60+ artifact definitions across AWS, Azure, and GCP, plus curated baseline IR packs per cloud (baseline-ir-aws, baseline-ir-azure, baseline-ir-gcp).

AWS log sources

AWS inventory and posture

Review the read only IAM policy before any engagement: docs/iam-policies/aws-collector-readonly.json.

Azure

Review read only permissions before any engagement:

• ARM: docs/iam-policies/azure-collector-readonly.json
• Microsoft Graph: docs/iam-policies/azure-collector-graph.json
• M365 / Exchange UAL search: docs/iam-policies/azure-collector-m365.json

Identity, M365, and control plane

Network, data access, and Log Analytics

Collect a subset with --collectors, for example: ventra collect azure --case CASE-2026-0042 --collectors activity_log,entra_signin.

GCP

GCP collectors cover Cloud Audit Logs (admin, system, data access), login events, SCC and Cloud Monitoring findings, VPC flow / firewall / NAT and network posture, load balancer / CDN / API Gateway / DNS / Cloud Armor, Cloud Storage / BigQuery / Cloud SQL / Secret Manager access, GCE and Cloud Functions inventory and logs, GKE audit, IAM policy snapshot, and logging posture. Run the baseline pack:

ventra collect gcp --pack baseline-ir-gcp --case CASE-2026-0042 --project my-project --out ~/ventra-evidence

See docs/artifacts.md for the catalog layout, artifacts/packs/baseline-ir-gcp.yaml for the curated IR bundle, and the console Docs → Google Cloud Platform → Collectors pages for per-collector permissions and parameters (sourced from the artifact YAML).

Analyst console

After ingest, investigation panels map directly to collector output. The console operates in two modes:

Investigate panels

Panel titles follow the case cloud (AWS defaults below; Azure and GCP rename several panels).

Role based access control (Responder, Investigator, Data Custodian, Analyst) is enforced server side. Investigators can import cases and export evidence bundles for downstream SIEM workflows (Elastic NDJSON export and Logstash pipelines under ingester/pipelines/).

Usage

Requirements

• Python 3.11+
• uv (recommended), or pipx / pip
• AWS: credentials with the read only collector policy attached (CloudShell works out of the box)
• Azure: az login
• GCP: Application default credentials or a service account JSON key
• Console: included in the package — after installing, run ventra gui from any directory (no Node.js, no clone). Use a git checkout only when developing the UI (ventra gui --dev-source).

Install options

See Quickstart for uvx / uv tool install / pipx / pip. Other ways in:

# Pin a release (e.g. for an engagement)
uv tool install 'ventra==1.0.0'
uvx ventra@1.0.0 --version

# Install a wheel you were handed
uv tool install ./ventra-1.0.0-py3-none-any.whl

# One-liner installer (prefers pipx, falls back to uv)
curl -fsSL https://raw.githubusercontent.com/Haggag-22/Ventra/main/bin/install.sh | bash

Extras. The base install already carries every cloud SDK. The per-cloud sets are also published as extras — ventra[aws], ventra[azure], ventra[gcp], ventra[kubernetes], and ventra[all] — so an install spec can name the clouds it relies on. Two optional features are extras only:

uv tool install 'ventra[sftp]'
uvx --from 'ventra[sftp]' ventra collect aws --transport sftp:… --case CASE-2026-0042
pipx install 'ventra[sftp]'

Development (local clone)

git clone https://github.com/Haggag-22/Ventra.git
cd Ventra
uv sync                              # .venv with locked deps + dev tools (pytest, ruff), editable
uv run pytest
uv run ruff check && uv run ruff format --check
uv run ventra gui                    # console with hot reload

Prefer plain pip-style tooling? uv venv && uv pip install -e ".[dev]" (or python -m pip install -e ".[dev]" in any 3.11+ virtualenv) gives the same editable install.

uv build produces the sdist and wheel in dist/. Releasing to PyPI: tag the commit — the version comes from git, not from pyproject.toml. See RELEASING.md and CONTRIBUTING.md.

git tag v1.0.0
git push origin v1.0.0

AWS CloudShell (recommended for client side collection)

# Review the read only policy first:
# docs/iam-policies/aws-collector-readonly.json

curl -fsSL https://raw.githubusercontent.com/Haggag-22/Ventra/main/bin/install-cloudshell.sh | bash

ventra collect aws \
  --case CASE-2026-0042 \
  --since 2026-05-01 \
  --out ~/ventra-evidence

The installer upgrades to the latest PyPI release on each run. Pin a version for an engagement with VENTRA_INSTALL_SPEC='ventra==1.0.0'.

Azure (host / IR workstation)

Use a client service principal from your machine. Flags override AZURE_* env vars:

ventra collect azure \
  --case CASE-2026-0042 \
  --tenant-id "<tenant-id>" \
  --client-id "<app-client-id>" \
  --client-secret "<secret>" \
  --subscription "<subscription-id>" \
  --since 2026-05-01 \
  --out ~/ventra-evidence

Certificate auth instead of a secret:

ventra collect azure \
  --case CASE-2026-0042 \
  --tenant-id "<tenant-id>" \
  --client-id "<app-client-id>" \
  --client-certificate /path/to/sp.pem \
  --subscription "<subscription-id>" \
  --out ~/ventra-evidence

Or set AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET (or AZURE_CLIENT_CERTIFICATE_PATH) in the environment and omit the flags.

GCP (host / IR workstation)

ventra collect gcp \
  --pack baseline-ir-gcp \
  --case CASE-2026-0042 \
  --project my-gcp-project \
  --since 2026-05-01 \
  --out ~/ventra-evidence

AWS (host / IR workstation)

Use a named profile from ~/.aws/credentials:

ventra collect aws \
  --case CASE-2026-0042 \
  --profile client-readonly \
  --since 2026-05-01 \
  --out ~/ventra-evidence

--profile is equivalent to AWS_PROFILE for that run. The profile name is recorded in the package manifest (not the secret key).

Operator kits and packs

Build a kit zip from the CLI or the Acquire tab in the console:

ventra kit build \
  --cloud aws \
  --pack baseline-ir-aws \
  --case CASE-2026-0042 \
  --out kit.zip

The kit contains acquisition.yaml, artifact YAML copies, narrowed IAM, and a bootstrap script for the operator to run in Cloud Shell. See docs/artifacts.md.

Investigate (IR workstation)

uv tool install ventra   # once (or: pipx install ventra)
ventra gui               # opens the console in your browser

Works from any directory after uv tool install / pipx install. Case data defaults to ~/.ventra (or ~/Library/Application Support/Ventra on macOS). Override with VENTRA_HOME.

From a git checkout, ventra gui still supports hot-reload development (--dev-source forces that mode even if a static build is present).

Import a package from the Cases screen, use Import from S3 for enterprise handoff, or run ventra import / ventra-ingest from the CLI.

Export a case to Elastic friendly NDJSON:

ventra-export --case-dir ./cases/CASE-2026-0042 --out ./export

Full operator steps: docs/runbooks/operator.md
Full analyst workflow: docs/runbooks/analyst.md

Available collectors

Running ventra collect aws, ventra collect azure, or ventra collect gcp executes every registered collector for that cloud unless you pass --collectors, --pack, or --acquisition. List them with:

ventra collect aws --list-collectors
ventra collect azure --list-collectors
ventra collect gcp --list-collectors
ventra collect aws --list-packs
ventra artifacts list --cloud gcp

Control plane and audit

Identity and access

Network and edge

Detections and findings

Workloads and data access

CLI reference

Common flags: --case, --since, --until, --regions, --out, --no-ingest, --transport, --collectors, --pack, --acquisition.

AWS host auth: --profile <name> (or AWS_PROFILE). Azure host auth: --tenant-id, --client-id, --client-secret or --client-certificate, plus --subscription (comma separated). Env vars AZURE_* work when flags are omitted. GCP: --project and application default credentials or a service account key.

For M365 UAL filters: --ual-users, --ual-operations, and related --ual-* flags.

What Ventra is not

• Not a SIEM: cases are scoped investigations, not always on log pipelines.
• Not EDR or disk forensics: OS internals, memory, and imaging stay with dedicated tools.
• Not a containment platform: the collector never modifies, isolates, or terminates resources.
• Not long term storage: Ventra defines the evidence format; retention is the IR team's choice.

Documentation

Status

AWS, Azure, and GCP collectors are supported end to end: demo fixtures, ingest, and console panels. The Acquire builder (artifact library, packs, IAM preview, operator handoff) is shipped. Enterprise scale work (streaming collectors, S3 ingest workers, SSO, managed collection workers) is in progress under Track D.

See ROADMAP.md for current phase detail.

Contributing, security, license

• CONTRIBUTING.md — dev setup, tests, lint, release flow
• SECURITY.md — report vulnerabilities privately
• CODE_OF_CONDUCT.md — Contributor Covenant

Apache-2.0. No telemetry.