How onesavielabs/bastet works
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
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: scan.py Scan · client.py n8n client · main.py CLI main · eval.py Eval
Components 18
CLI orchestration
Python entrypoint, commands, models, and reporting.
- CLI main · Top-level command dispatcher and runtime entrypoint.
cli/main.py - Scan · Finds Solidity files and sends them into analysis workflows.
cli/commands/scan/scan.py - Fetch · Pulls verified on-chain contract sources from external providers.
cli/commands/fetch/fetch.py - Eval · Runs benchmark cases and compares findings to ground truth.
cli/commands/evaluate/eval.py - Init import · Bootstraps a fresh n8n instance by importing bundled workflows.
cli/commands/init/import_workflow.py - Audit report · Normalized finding shape used for scan and evaluation output.
cli/models/audit_report.py - Execution models · Typed models for n8n executions, nodes, and related payloads.
cli/models/n8n - Report gen · Formats findings into JSON, Markdown, and PDF outputs.
cli/utils/report_generator
n8n integration
HTTP client boundary and bundled workflow definitions.
- n8n client · Base client and configuration for the n8n REST API.
cli/http_client/n8n/client.py - Workflow API · Workflow CRUD and execution-triggering integration.
cli/http_client/n8n/clients/workflow.py - Control APIs · Executions, credentials, users, tags, variables, audit, and source control clients.
cli/http_client/n8n/clients - n8n models · Typed workflow, node, tag, and settings models used to parse API responses.
cli/http_client/n8n/model - 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 · Ground truth, repos, reports, and scan queue inputs.
dataset - Dataset guide · Dataset layout and usage notes for local corpus workflows.
dataset/README.md - Scan queue · Queued local targets for batch scanning runs.
dataset/scan_queue
Deployment
Container and CI/CD entrypoints for local and automated runs.
- Docker stack · Local containerized runtime for CLI, n8n, and PostgreSQL.
docker-compose.yml - CI stack · GitHub Actions and GitLab CI wrappers for unattended scans.
docker-compose.cicd.yml
Connections 24
- 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.