# onesavielabs/bastet architecture

> Architecture diagram of the GitHub repository onesavielabs/bastet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/onesavielabs/bastet
- Repository: https://github.com/onesavielabs/bastet

## Overview

1. **What Bastet is**
   Bastet is a Python-based CLI tool plus a set of n8n workflow definitions and datasets for smart-contract vulnerability detection. The repository is split between the **Bastet CLI**, **local n8n automation**, and **dataset/artifact storage**.

2. **Primary runtime boundary: the CLI**
   The `cli/` package is the operational entry point (`cli/main.py`). It exposes commands for:
   - `init`: import bundled n8n workflows
   - `scan`: recursively analyze Solidity files in a directory
   - `fetch`: pull verified on-chain contract source code
   - `eval`: run the benchmark/evaluation loop against the dataset

   In architecture terms, the CLI is the orchestrator; it does not implement the detection logic itself.

3. **Detection engine lives in n8n, not in Python**
   The actual vulnerability analysis is delegated to **n8n workflows** stored in `n8n_workflow/*.json`. The CLI imports and triggers these workflows through n8n’s API/webhooks. This creates a clear boundary:
   - Python handles ingestion, coordination, and reporting
   - n8n handles prompt/workflow execution and LLM-backed analysis

4. **Local service stack**
   The repository includes `docker-compose.yml`, `docker-compose.cicd.yml`, `Dockerfile`, and `init/01-n8n.sql`, indicating a containerized local stack. The README states Bastet runs with:
   - **n8n** as the workflow automation service
   - **PostgreSQL** as the backing datastore for results/state
   - environment variables in `.env` for n8n API keys and OpenAI credential IDs

   So the local deployment boundary is: CLI container/process → n8n service → database.

5. **HTTP client layer for n8n integration**
   `cli/http_client/n8n/` is a dedicated client library around the n8n REST API. It includes:
   - configuration and base client logic
   - per-resource clients for workflows, executions, credentials, users, tags, variables, audit, source control
   - typed models for workflows, nodes, settings, and tags

   This layer is the integration boundary between Bastet and the n8n control plane.

6. **Scanning data flow**
   The `scan` command walks the target directory for `.sol` files, sends contract content into the active n8n vulnerability workflows, then aggregates results. The output is normalized into reports via `cli/utils/report_generator/`, which can emit:
   - CSV
   - JSON
   - Markdown
   - PDF

   The scan path is therefore: filesystem source code → n8n analysis workflow(s) → structured findings → generated reports.

7. **On-chain source acquisition**
   The `fetch` command uses Etherscan as an external data source for verified contract source code and dependencies. Downloaded sources are stored under `dataset/onchain-sources/<address>`. This is a separate ingestion path from the local dataset and feeds later scanning or manual review.

8. **Evaluation pipeline**
   The `eval` command is a benchmark harness. It reads:
   - `dataset/dataset.csv` for ground truth
   - `dataset/repos/` and `dataset/reports/` for project inputs and audit artifacts

   It sends cases into an active webhook-based n8n workflow and compares outputs to compute confusion metrics such as true positives, false positives, etc. This is a data-science/benchmarking loop rather than a production scanning loop.

9. **Dataset and artifact storage**
   The `dataset/` directory is the main offline corpus boundary. It stores:
   - project repositories
   - audit reports
   - benchmark labels (`dataset.csv`)
   - queue inputs for scanning (`dataset/scan_queue`)

   Bastet’s architecture assumes the dataset is mounted or unpacked locally; the CLI consumes it directly from the filesystem.

10. **Workflow initialization and credentials**
   `cli/commands/init/import_workflow.py` and the bundled `n8n_workflow/*.json` files show that Bastet can bootstrap a fresh n8n instance by importing predefined workflows. The setup depends on environment-provided credentials such as:
   - `N8N_API_KEY`
   - `N8N_OPENAI_CREDENTIAL_ID`
   - `ETHERSCAN_API_KEY`

   This makes external service access an explicit configuration boundary, not hard-coded logic.

11. **Domain models and output shape**
   `cli/models/` contains internal typed models for audits, executions, and nodes. These are used to normalize n8n responses and report output. The README also defines the expected JSON schema for evaluation results, so the repository has a clear contract for findings: summary, severity, vulnerability details, code snippet, and recommendation.

12. **CI/CD and distribution**
   The repository includes example GitHub Actions and GitLab CI templates, plus a dedicated CI compose file. This indicates Bastet is designed to run both locally and in pipelines, where scans can be automated on pushes or merge requests. The CI path reuses the same CLI and n8n-backed analysis stack, just containerized for unattended execution.

Main entry points: [`cli/commands/scan/scan.py`](https://github.com/onesavielabs/bastet/blob/main/cli/commands/scan/scan.py) (Scan), [`cli/http_client/n8n/client.py`](https://github.com/onesavielabs/bastet/blob/main/cli/http_client/n8n/client.py) (n8n client), [`cli/main.py`](https://github.com/onesavielabs/bastet/blob/main/cli/main.py) (CLI main), [`cli/commands/evaluate/eval.py`](https://github.com/onesavielabs/bastet/blob/main/cli/commands/evaluate/eval.py) (Eval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli["CLI orchestration"]
  node_cli_main["CLI main<br/>entrypoint<br/>[main.py]"]
  node_cmd_scan["Scan<br/>command<br/>[scan.py]"]
  node_cmd_fetch["Fetch<br/>command<br/>[fetch.py]"]
  node_cmd_eval["Eval<br/>command<br/>[eval.py]"]
  node_cmd_init["Init import<br/>command<br/>[import_workflow.py]"]
  node_audit_report["Audit report<br/>schema<br/>[audit_report.py]"]
  node_n8n_exec_models["Execution models<br/>schema"]
  node_report_gen["Report gen<br/>reporting"]
end

subgraph group_group_n8n["n8n integration"]
  node_n8n_client["n8n client<br/>http client<br/>[client.py]"]
  node_workflow_api["Workflow API<br/>resource client<br/>[workflow.py]"]
  node_ops_api["Control APIs<br/>resource clients"]
  node_n8n_models["n8n models<br/>schemas"]
  node_workflows["Workflows"]
end

subgraph group_group_data["Data corpus"]
  node_dataset_store[("Dataset store<br/>filesystem corpus")]
  node_dataset_readme["Dataset guide<br/>docs<br/>[README.md]"]
  node_scan_queue["Scan queue<br/>inputs"]
end

subgraph group_group_deploy["Deployment"]
  node_docker_stack["Docker stack<br/>compose stack<br/>[docker-compose.yml]"]
  node_cicd_stack["CI stack<br/>pipeline config"]
end

node_cli_main -->|"dispatches"| node_cmd_scan
node_cli_main -->|"dispatches"| node_cmd_fetch
node_cli_main -->|"dispatches"| node_cmd_eval
node_cli_main -->|"dispatches"| node_cmd_init
node_cmd_scan -->|"calls API"| node_n8n_client
node_cmd_fetch -->|"uses API"| node_n8n_client
node_cmd_eval -->|"triggers workflows"| node_n8n_client
node_cmd_init -->|"imports"| node_n8n_client
node_n8n_client -->|"wraps"| node_workflow_api
node_n8n_client -->|"wraps"| node_ops_api
node_workflow_api -->|"returns"| node_n8n_models
node_ops_api -->|"returns"| node_n8n_models
node_cmd_scan -->|"loads"| node_workflows
node_cmd_eval -->|"executes"| node_workflows
node_cmd_scan -->|"structures"| node_audit_report
node_cmd_scan -->|"formats"| node_report_gen
node_cmd_eval -->|"reads labels"| node_dataset_store
node_cmd_scan -->|"reads queue"| node_scan_queue
node_cmd_scan -->|"reads corpus"| node_dataset_store
node_cmd_fetch -->|"writes sources"| node_dataset_store
node_dataset_store -->|"documents"| node_dataset_readme
node_docker_stack -->|"runs"| node_cli_main
node_docker_stack -->|"hosts"| node_workflows
node_cicd_stack -->|"automates"| node_cmd_scan

click node_cli_main "https://github.com/onesavielabs/bastet/blob/main/cli/main.py"
click node_cmd_scan "https://github.com/onesavielabs/bastet/blob/main/cli/commands/scan/scan.py"
click node_cmd_fetch "https://github.com/onesavielabs/bastet/blob/main/cli/commands/fetch/fetch.py"
click node_cmd_eval "https://github.com/onesavielabs/bastet/blob/main/cli/commands/evaluate/eval.py"
click node_cmd_init "https://github.com/onesavielabs/bastet/blob/main/cli/commands/init/import_workflow.py"
click node_audit_report "https://github.com/onesavielabs/bastet/blob/main/cli/models/audit_report.py"
click node_n8n_exec_models "https://github.com/onesavielabs/bastet/tree/main/cli/models/n8n"
click node_report_gen "https://github.com/onesavielabs/bastet/tree/main/cli/utils/report_generator"
click node_n8n_client "https://github.com/onesavielabs/bastet/blob/main/cli/http_client/n8n/client.py"
click node_workflow_api "https://github.com/onesavielabs/bastet/blob/main/cli/http_client/n8n/clients/workflow.py"
click node_ops_api "https://github.com/onesavielabs/bastet/tree/main/cli/http_client/n8n/clients"
click node_n8n_models "https://github.com/onesavielabs/bastet/tree/main/cli/http_client/n8n/model"
click node_workflows "https://github.com/onesavielabs/bastet/tree/main/n8n_workflow"
click node_dataset_store "https://github.com/onesavielabs/bastet/tree/main/dataset"
click node_dataset_readme "https://github.com/onesavielabs/bastet/blob/main/dataset/README.md"
click node_scan_queue "https://github.com/onesavielabs/bastet/tree/main/dataset/scan_queue"
click node_docker_stack "https://github.com/onesavielabs/bastet/blob/main/docker-compose.yml"
click node_cicd_stack "https://github.com/onesavielabs/bastet/blob/main/docker-compose.cicd.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_main,node_cmd_scan,node_cmd_fetch,node_cmd_eval,node_cmd_init,node_audit_report,node_n8n_exec_models,node_report_gen toneBlue
class node_n8n_client,node_workflow_api,node_ops_api,node_n8n_models,node_workflows toneAmber
class node_dataset_store,node_dataset_readme,node_scan_queue toneMint
class node_docker_stack,node_cicd_stack toneRose
```

## Components

### CLI orchestration

Python entrypoint, commands, models, and reporting.

- [CLI main](https://github.com/onesavielabs/bastet/blob/main/cli/main.py): entrypoint · Top-level command dispatcher and runtime entrypoint. · `cli/main.py`
- [Scan](https://github.com/onesavielabs/bastet/blob/main/cli/commands/scan/scan.py): command · Finds Solidity files and sends them into analysis workflows. · `cli/commands/scan/scan.py`
- [Fetch](https://github.com/onesavielabs/bastet/blob/main/cli/commands/fetch/fetch.py): command · Pulls verified on-chain contract sources from external providers. · `cli/commands/fetch/fetch.py`
- [Eval](https://github.com/onesavielabs/bastet/blob/main/cli/commands/evaluate/eval.py): command · Runs benchmark cases and compares findings to ground truth. · `cli/commands/evaluate/eval.py`
- [Init import](https://github.com/onesavielabs/bastet/blob/main/cli/commands/init/import_workflow.py): command · Bootstraps a fresh n8n instance by importing bundled workflows. · `cli/commands/init/import_workflow.py`
- [Audit report](https://github.com/onesavielabs/bastet/blob/main/cli/models/audit_report.py): schema · Normalized finding shape used for scan and evaluation output. · `cli/models/audit_report.py`
- [Execution models](https://github.com/onesavielabs/bastet/tree/main/cli/models/n8n): schema · Typed models for n8n executions, nodes, and related payloads. · `cli/models/n8n`
- [Report gen](https://github.com/onesavielabs/bastet/tree/main/cli/utils/report_generator): reporting · Formats findings into JSON, Markdown, and PDF outputs. · `cli/utils/report_generator`

### n8n integration

HTTP client boundary and bundled workflow definitions.

- [n8n client](https://github.com/onesavielabs/bastet/blob/main/cli/http_client/n8n/client.py): http client · Base client and configuration for the n8n REST API. · `cli/http_client/n8n/client.py`
- [Workflow API](https://github.com/onesavielabs/bastet/blob/main/cli/http_client/n8n/clients/workflow.py): resource client · Workflow CRUD and execution-triggering integration. · `cli/http_client/n8n/clients/workflow.py`
- [Control APIs](https://github.com/onesavielabs/bastet/tree/main/cli/http_client/n8n/clients): resource clients · Executions, credentials, users, tags, variables, audit, and source control clients. · `cli/http_client/n8n/clients`
- [n8n models](https://github.com/onesavielabs/bastet/tree/main/cli/http_client/n8n/model): schemas · Typed workflow, node, tag, and settings models used to parse API responses. · `cli/http_client/n8n/model`
- [Workflows](https://github.com/onesavielabs/bastet/tree/main/n8n_workflow): json workflows · Bundled detection workflows imported into n8n and invoked during scans and evals. · `n8n_workflow`

### Data corpus

Offline datasets, scan queue, and stored artifacts.

- [Dataset store](https://github.com/onesavielabs/bastet/tree/main/dataset): filesystem corpus · Ground truth, repos, reports, and scan queue inputs. · `dataset`
- [Dataset guide](https://github.com/onesavielabs/bastet/blob/main/dataset/README.md): docs · Dataset layout and usage notes for local corpus workflows. · `dataset/README.md`
- [Scan queue](https://github.com/onesavielabs/bastet/tree/main/dataset/scan_queue): inputs · Queued local targets for batch scanning runs. · `dataset/scan_queue`

### Deployment

Container and CI/CD entrypoints for local and automated runs.

- [Docker stack](https://github.com/onesavielabs/bastet/blob/main/docker-compose.yml): compose stack · Local containerized runtime for CLI, n8n, and PostgreSQL. · `docker-compose.yml`
- [CI stack](https://github.com/onesavielabs/bastet/blob/main/docker-compose.cicd.yml): pipeline config · GitHub Actions and GitLab CI wrappers for unattended scans. · `docker-compose.cicd.yml`

## Connections

- CLI main → Scan: dispatches · CLI routes scan subcommands to the scanning pipeline.
- CLI main → Fetch: dispatches · CLI routes source acquisition commands.
- CLI main → Eval: dispatches · CLI routes benchmark commands.
- CLI main → Init import: dispatches · CLI routes bootstrap/import commands.
- Scan → n8n client: calls API · Scan orchestration uses the n8n REST client boundary.
- Fetch → n8n client: uses API · Fetch flow shares API configuration and external credentials.
- Eval → n8n client: triggers workflows · Eval harness sends benchmark cases into n8n workflows.
- Init import → n8n client: imports · Initialization talks to n8n to seed workflows and credentials.
- n8n client → Workflow API: wraps · Main integration surface for workflow operations.
- n8n client → Control APIs: wraps · Supporting control-plane resources are exposed through dedicated clients.
- Workflow API → n8n models: returns · Workflow responses are parsed into typed models.
- Control APIs → n8n models: returns · Auxiliary resource payloads share typed schemas where needed.
- Scan → Workflows: loads · Bundled workflow definitions are the analysis engine target.
- Eval → Workflows: executes · Benchmark runs reuse the same n8n workflow boundary.
- Scan → Audit report: structures · Findings are normalized into internal audit result models.
- Scan → Report gen: formats · Scan results are rendered into human-readable reports.
- Eval → Dataset store: reads labels · Evaluation consumes ground-truth and project artifacts.
- Scan → Scan queue: reads queue · Batch scanning can consume queued local targets.
- Scan → Dataset store: reads corpus · Scan workflows can consume local corpus inputs and datasets.
- Fetch → Dataset store: writes sources · Fetched verified sources are stored in the local dataset area.
- Dataset store → Dataset guide: documents · Repository documentation explains the local corpus layout.
- Docker stack → CLI main: runs · Containerized runtime launches the CLI entrypoint.
- Docker stack → Workflows: hosts · Local stack provisions bundled workflows for n8n.
- CI stack → Scan: automates · CI templates run the same scan orchestration in pipelines.
