Related Pages

Related topics: Quick Start Guide, System Architecture, Scanner Pipeline

Introduction to Velonus

Velonus is an open-source security scanner CLI designed to detect secrets, vulnerabilities, and security issues in codebases. It aggregates multiple industry-standard security tools into a unified pipeline with normalized output formats and deduplication logic. Velonus is particularly useful for development teams seeking to integrate security scanning into their CI/CD pipelines and local development workflows.

Overview

Velonus provides a command-line interface that orchestrates multiple security scanners to analyze source code and dependencies. The tool normalizes findings from different sources into a canonical data model, removes duplicates, and presents results in multiple output formats including terminal, JSON, and SARIF. Sources: README.md

The project is structured as a monorepo with three main packages:

Sources: CONTRIBUTING.md

Architecture

High-Level Component Architecture

graph TD
    User --> CLI[CLI Interface<br/>apps/cli/shield/]
    CLI --> Scanner[Scanner Package<br/>packages/scanner/]
    Scanner --> Secrets[Secrets Detector<br/>trufflehog + entropy]
    Scanner --> Bandit[Bandit Detector<br/>Python security linter]
    Scanner --> Semgrep[Semgrep Detector<br/>Static analysis]
    Scanner --> PipAudit[pip-audit Detector<br/>Dependency vulnerabilities]
    Scanner --> Safety[Safety Detector<br/>Python package safety]
    
    Scanner --> Normalizer[Normalizer Package<br/>packages/normalizer/]
    Normalizer --> Models[NormalizedFinding Model]
    Models --> Deduplicator[Deduplication Filter]
    
    Deduplicator --> Formatters[Output Formatters]
    Formatters --> Terminal[Terminal Formatter<br/>Rich tables]
    Formatters --> JSON[JSON Formatter]
    Formatters --> SARIF[SARIF Formatter<br/>GitHub Code Scanning]

Scanner Pipeline Flow

graph LR
    A[Input Path] --> B[Secrets Scan]
    B --> C[Bandit Scan]
    C --> D[Semgrep Scan]
    D --> E[pip-audit Scan]
    E --> F[Safety Scan]
    F --> G[Normalize]
    G --> H[Deduplicate]
    H --> I[Format Output]

Sources: packages/normalizer/deduplicator.py:1-30

Supported Security Tools

Velonus wraps and orchestrates the following security scanners:

Scanner Comparison Table

Sources: README.md Sources: packages/scanner/scanner/detectors/secrets.py:1-50

Data Models

NormalizedFinding Schema

The core data model used throughout Velonus is NormalizedFinding, which provides a canonical representation of security findings regardless of their source tool. Sources: packages/normalizer/models.py:1-50

Sources: packages/normalizer/models.py:50-75

Severity Levels

Sources: apps/cli/README.md

Core Components

Scanner Package

The scanner package (packages/scanner/) contains wrappers for each security tool. Each detector implements a common interface and produces RawFinding objects that are later normalized.

#### Secrets Detector

The secrets detector performs two types of secret scanning:

1. TruffleHog Integration: Scans for verified and potential secrets using known detector patterns
2. Entropy-based Fallback: Uses Shannon entropy thresholding to detect high-entropy strings in credential assignments

# Detection logic in secrets.py
if entropy >= _ENTROPY_THRESHOLD:
    findings.append(
        RawFinding(
            tool="secrets",
            rule_id="high-entropy-secret",
            severity="CRITICAL",
            message=f"High-entropy string detected (Shannon entropy={entropy:.2f})",
            metadata={"entropy": round(entropy, 3)},
        )
    )

Sources: packages/scanner/scanner/detectors/secrets.py:1-60

#### pip-audit and Safety Detectors

Both dependency vulnerability detectors extract CVSS v3 scores and map them to Velonus severity levels:

# Severity mapping from CVSS score
if score >= _CVSS_CRITICAL:
    return "CRITICAL"
if score >= _CVSS_HIGH:
    return "HIGH"
if score >= _CVSS_MEDIUM:
    return "MEDIUM"
return "LOW"

Sources: packages/scanner/scanner/detectors/pip_audit.py:1-30 Sources: packages/scanner/scanner/detectors/safety.py:1-50

Normalizer Package

The normalizer package (packages/normalizer/) transforms raw findings from various tools into the canonical NormalizedFinding format and handles deduplication.

#### Deduplication Strategy

Deduplication uses the deterministic id field as the key:

• Findings are processed in pipeline order: secrets → bandit → semgrep → pip-audit → safety
• The first occurrence of each id is kept (highest-priority tool wins)
• Subsequent duplicates are discarded at DEBUG level

Important: Cross-tool duplicates (e.g., bandit and semgrep flagging the same eval() call) are intentionally not deduplicated because they have different id values (the id includes tool). This allows the AI layer to analyze each finding independently. Sources: packages/normalizer/deduplicator.py:1-35

CLI Package (Shield)

The CLI package (apps/cli/shield/) provides the user interface, argument parsing, and output formatting.

#### Output Formatters

The SARIF formatter includes helper functions for URI conversion and rule naming:

def _rule_id_to_name(rule_id: str) -> str:
    """Convert rule_id to PascalCase display name for SARIF."""
    base = rule_id.split("/")[-1]
    return "".join(word.capitalize() for word in base.replace("-", "_").split("_"))

Sources: apps/cli/shield/formatters/sarif.py:1-40

CLI Usage

Basic Commands

# Scan current directory
velonus scan ./

# Scan with severity filter
velonus scan ./ --severity high

# Output as JSON
velonus scan ./ --format json

# Export SARIF for GitHub Security tab
velonus scan ./ --format sarif -o results/velonus.sarif

# Show verbose output
velonus scan ./ --verbose

Command Options

Exit Codes

Exit code 1 on HIGH/CRITICAL is intentional and enables CI gate functionality. Sources: apps/cli/README.md

CI/CD Integration

GitHub Actions

name: Velonus Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install velonus-cli
        run: pip install -e apps/cli
      - name: Run security scan
        run: velonus scan ./ --severity high

Sources: README.md

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: velonus-scan
        name: Velonus Security Scan
        entry: velonus scan
        args: ["./", "--severity", "high"]
        language: system
        pass_filenames: false

Development Setup

Requirements

• Python 3.10+ Sources: CONTRIBUTING.md
• uv package manager

Setup Commands

# Clone and enter directory
git clone https://github.com/AliAmmar15/Velonus
cd Velonus

# Install all workspace packages and dev dependencies
uv sync --all-extras --dev

# Activate virtual environment
source .venv/bin/activate

# Install packages in editable mode
pip install -e apps/cli
pip install -e packages/scanner
pip install -e packages/normalizer

# Verify installation
velonus --help

Code Quality Standards

All code must pass the following checks before PR submission:

Sources: CONTRIBUTING.md

PR Guidelines

1. One feature or fix per PR — do not bundle unrelated changes
2. Tests are required — every new scanner wrapper, formatter, or utility needs matching unit tests
3. Keep it small — PRs under 400 lines of diff get reviewed faster
4. No AI-generated placeholder code — every function must be functional and tested
5. Target main — all PRs merge into main; no long-lived feature branches

Roadmap

Sources: README.md

Alpha Status

Velonus is currently in alpha. The tool is functional and actively used internally, but users should expect rough edges. The development team encourages feedback through GitHub issues. Sources: README.md

Related Pages

Related topics: Introduction to Velonus, CLI Components

Quick Start Guide

Overview

The Quick Start Guide provides developers and security teams with the essential steps to install, configure, and run Velonus for security scanning of Python projects. Velonus is a multi-tool security scanner that aggregates findings from Bandit, Semgrep, pip-audit, Safety, and TruffleHog into a unified output with severity-based filtering.

This guide covers:

• Installation from source
• Basic scan execution
• Output format configuration
• Severity filtering
• CI/CD integration patterns

Sources: README.md:1-10

Prerequisites

System Requirements

Required Tools for Full Functionality

Velonus gracefully handles missing tools—scanners skip silently if their dependency is not installed, logging a warning message.

Sources: packages/scanner/scanner/detectors/semgrep.py:1-20

Installation

From Source

Clone the repository and install the CLI package:

git clone https://github.com/AliAmmar15/Velonus.git
cd Velonus
pip install -e apps/cli

Verify Installation

velonus --version

Sources: apps/cli/README.md:1-30

Basic Usage

Running Your First Scan

Scan the current directory:

velonus scan ./

Scan a specific project path:

velonus scan ./my-python-project

Workflow Overview

graph TD
    A[User runs velonus scan] --> B[Resolve target path]
    B --> C[Run secret detection<br/>TruffleHog + entropy scan]
    C --> D[Run Bandit static analysis]
    D --> E[Run Semgrep security rules]
    E --> F[Run pip-audit dependency scan]
    F --> G[Run Safety dependency check]
    G --> H[Normalize all findings]
    H --> I[Filter by severity]
    I --> J[Format output]
    J --> K[Print to terminal<br/>or write to file]
    K --> L[Exit with status code]

Sources: apps/cli/shield/commands/scan.py:1-50

Scan Command Options

Syntax

velonus scan [PATH] [OPTIONS]

Options Reference

Sources: apps/cli/README.md:40-60

Severity Filtering Examples

# Show all findings (info and above)
velonus scan ./

# Only HIGH and CRITICAL findings
velonus scan ./ --severity high

# Only CRITICAL findings
velonus scan ./ --severity critical

Output Format Examples

# Default: rich terminal table with colored output
velonus scan ./

# JSON output for piping
velonus scan ./ --format json

# SARIF output for GitHub Security tab
velonus scan ./ --format sarif

# Write SARIF to custom path
velonus scan ./ -o results/velonus.sarif

Sources: apps/cli/README.md:70-100

Output Formats

Terminal (Default)

Rich table with severity badges, file paths, line numbers, rule IDs, and messages. Optimized for interactive use.

JSON

Machine-readable format suitable for piping into other tools:

velonus scan ./ --format json | python -m json.tool
velonus scan ./ --format json > scan-results.json

SARIF

Static Analysis Results Interchange Format for GitHub Code Scanning and VS Code SARIF Viewer integration:

velonus scan ./ --format sarif
velonus scan ./ -o results/scan.sarif

Sources: README.md:30-60

Exit Codes

The exit code behavior is intentional for CI/CD gate integration:

# CI will fail if HIGH or CRITICAL findings exist
velonus scan ./ --severity high

Sources: apps/cli/README.md:100-115

CI/CD Integration

GitHub Actions

name: Velonus Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install velonus-cli
        run: pip install -e apps/cli

      - name: Run security scan
        run: velonus scan ./ --severity high
        # exits 1 if HIGH or CRITICAL findings found

Pre-commit Hook

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: velonus-scan
        name: Velonus Security Scan
        entry: velonus scan
        args: ["./", "--severity", "high"]
        language: system
        pass_filenames: false

Sources: README.md:60-95

Common Workflows

Quick Security Audit

velonus scan ./ --severity high

Comprehensive Scan with Verbose Output

velonus scan ./ --verbose --format json > full-scan.json

Generate SARIF for GitHub Security Tab

velonus scan ./ --format sarif -o velonus.sarif

Export Findings as JSON

velonus scan ./ --format json --severity high > findings.json

Project Status

Velonus follows a phased development approach:

Sources: README.md:100-120

Next Steps

• Configuration: Explore velonus config for API URL settings (Phase 2)
• Authentication: Set up API authentication with velonus auth login (Phase 2)
• Contributing: See CONTRIBUTING.md for development setup and PR guidelines
• Issues: Report problems at github.com/AliAmmar15/Velonus/issues

Velonus is in alpha. The core scanning functionality works reliably—use it in CI today with the exit code gate.

Sources: README.md:120-130

Related Pages

Related topics: Introduction to Velonus, CLI Components, API Backend, Scanner Pipeline

System Architecture

Overview

Velonus is a multi-tool security scanning platform designed to identify vulnerabilities in Python projects through a modular scanner pipeline. The system integrates multiple security tools (TruffleHog, Semgrep, Bandit, pip-audit, Safety) into a unified CLI experience with flexible output formats for both interactive use and CI/CD integration.

Sources: README.md

High-Level Architecture

Velonus follows a layered architecture with clear separation between the CLI interface, scanner core, detectors, and output formatters.

graph TD
    subgraph "CLI Layer"
        CLI[velonus CLI]
        Commands[scan / auth / config]
    end
    
    subgraph "Core Layer"
        Scanner[Scanner Pipeline]
        Normalizer[Normalizer]
        Formatters[Formatters]
    end
    
    subgraph "Detector Layer"
        Secrets[Secrets Detector]
        Semgrep[Semgrep Detector]
        PipAudit[pip-audit Detector]
        Safety[Safety Detector]
    end
    
    subgraph "External Tools"
        TH[TruffleHog]
        SG[Semgrep Binary]
        PA[pip-audit]
        SF[safety]
    end
    
    CLI --> Commands
    Commands --> Scanner
    Scanner --> Normalizer
    Scanner --> Detectors
    Detectors --> TH
    Detectors --> SG
    Detectors --> PA
    Detectors --> SF
    Normalizer --> Formatters
    Formatters --> Output[terminal / json / sarif]

Project Structure

The repository is organized as a monorepo with separate packages and applications.

Sources: CONTRIBUTING.md:6-8

Scanner Pipeline

Pipeline Architecture

The scanner pipeline orchestrates multiple security tools and aggregates their findings into a unified format.

graph LR
    Input[Target Path] --> Resolve[Path Resolution]
    Resolve --> SD[Secrets Detection]
    Resolve --> SEM[Semgrep Scan]
    Resolve --> PA[pip-audit]
    Resolve --> SF[Safety Scan]
    SD --> RF1[RawFinding]
    SEM --> RF2[RawFinding]
    PA --> RF3[RawFinding]
    SF --> RF4[RawFinding]
    RF1 --> Aggregate[Aggregate Findings]
    RF2 --> Aggregate
    RF3 --> Aggregate
    RF4 --> Aggregate
    Aggregate --> Normalize[Normalize to NormalizedFinding]
    Normalize --> Format[Format Output]

Core Components

#### RawFinding Data Model

All detectors produce RawFinding objects as the initial representation of a security finding:

RawFinding(
    tool="pip-audit",           # Source tool identifier
    rule_id="CVE-2023-12345",   # Vulnerability identifier
    file="requirements.txt",    # Affected file path
    line=0,                      # Line number (0 for dep issues)
    severity="HIGH",             # CRITICAL/HIGH/MEDIUM/LOW/INFO
    message="...",               # Human-readable message
    code_snippet="...",          # Relevant code context
    metadata={                   # Tool-specific metadata
        "package_name": "requests",
        "package_version": "2.28.0",
        "cvss_score": 7.5,
        "fix_available": True
    }
)

Sources: packages/scanner/scanner/detectors/pip_audit.py:49-61

#### NormalizedFinding

The normalizer transforms RawFinding objects into a standardized NormalizedFinding format for consistent output across all tools.

Detector Interface

All detectors implement a common interface:

Security Detectors

Secrets Detector

The secrets detector identifies hardcoded credentials and sensitive information using two complementary approaches:

#### TruffleHog Integration

Primary detection method that leverages TruffleHog's extensive secret detection rules.

RawFinding(
    tool="secrets",
    rule_id=f"trufflehog-{detector_name.lower().replace(' ', '-')}",
    file=file_path,
    line=line_num,
    severity="CRITICAL",
    message=f"{'Verified' if verified else 'Potential'} secret detected [{detector_name}]",
    metadata={
        "detector": detector_name,
        "verified": verified,
        "decoder": decoder_name
    }
)

Sources: packages/scanner/detectors/secrets.py:45-57

#### Entropy-Based Fallback

When TruffleHog is unavailable, a Shannon entropy-based scanner detects high-entropy strings in credential assignments.

RawFinding(
    tool="secrets",
    rule_id="high-entropy-secret",
    severity="CRITICAL",
    message=f"High-entropy string in secret assignment (Shannon entropy={entropy:.2f})",
    metadata={"entropy": round(entropy, 3)}
)

Sources: packages/scanner/detectors/secrets.py:78-91

Semgrep Detector

Runs Semgrep with the p/python ruleset for Python-specific security analysis.

graph TD
    Check[Check semgrep availability] -->|found| Run[Run semgrep scan]
    Check -->|not found| Skip[Return empty list + warning]
    Run --> Parse[Parse JSON output]
    Parse --> Extract[Extract CWE/OWASP metadata]
    Extract --> Create[Create RawFinding objects]

Configuration:

• Ruleset: p/python
• Flags: --json --quiet --metrics=off
• Exit code 1: Findings present (not an error)
• Exit code 2+: Real error

Sources: packages/scanner/scanner/detectors/semgrep.py:35-55

Metadata Extraction:

pip-audit Detector

Scans Python dependencies for known vulnerabilities using pip-audit.

Finding Structure:

RawFinding(
    tool="pip-audit",
    rule_id=vuln_id,
    file=attribution_path,
    line=0,  # Dependency vulnerabilities are file-level
    severity=severity,
    metadata={
        "package_name": package_name,
        "package_version": package_version,
        "aliases": aliases,
        "fix_versions": fix_versions,
        "cvss_score": cvss_score,
        "cwe": _CWE,
        "owasp": _OWASP,
        "fix_available": bool(fix_versions)
    }
)

Sources: packages/scanner/scanner/detectors/pip_audit.py:49-61

CVSS to Severity Mapping:

Safety Detector

Handles both Safety v1 and v2 output formats for Python vulnerability scanning.

Supported Formats:

Vulnerability Entry Parsing:

# Required fields for v2
vuln_id: str = str(entry["vulnerability_id"])
package_name: str = str(entry["package_name"])
installed_version: str = str(entry["analyzed_version"])

# Optional fields
advisory: str = str(entry.get("advisory", ""))
cve: str = str(entry.get("CVE", ""))
fix_versions: list[str] = [str(v) for v in entry.get("fixed_versions", [])]

Sources: packages/scanner/scanner/detectors/safety.py:50-65

CLI Architecture

Command Structure

velonus [OPTIONS] COMMAND [ARGS]...

Sources: apps/cli/README.md

Scan Command Interface

velonus scan [PATH] [OPTIONS]

Exit Codes:

Output Formatters

Terminal Formatter

Rich-formatted table with colored severity badges:

┏━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Severity      ┃ Tool     ┃ Rule             ┃ Message    ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ 🔴 CRITICAL   │ secrets  │ aws-access-key   │ Hardcoded  │
│ 🟠 HIGH       │ bandit   │ B413             │ Blacklist  │

JSON Formatter

Structured JSON output for piping and tooling:

{
  "findings": [
    {
      "severity": "CRITICAL",
      "tool": "secrets",
      "rule_id": "trufflehog-aws-access-key",
      "file": "config.py",
      "line": 42,
      "message": "Verified secret detected [AWS Access Key]"
    }
  ]
}

SARIF Formatter

Static Analysis Results Interchange Format for GitHub Code Scanning integration.

Key SARIF Elements:

Rule ID Transformation:

secrets/aws-access-key-id → AwsAccessKeyId
generic-api-key → GenericApiKey

Sources: apps/cli/shield/formatters/sarif.py:40-58

Severity Classification

Sources: apps/cli/README.md

Development Standards

Code Quality Requirements

All code must pass:

Strict Requirements:

• Zero mypy errors in strict mode
• No type: ignore without explanation comment
• All functions must be functional and tested
• No AI-generated placeholder code

Sources: CONTRIBUTING.md:32-44

PR Guidelines

Roadmap

Sources: README.md

CI/CD Integration

GitHub Actions Workflow

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install velonus-cli
        run: pip install -e apps/cli
      - name: Run security scan
        run: velonus scan ./ --severity high

Pre-commit Hook

repos:
  - repo: local
    hooks:
      - id: velonus-scan
        name: Velonus Security Scan
        entry: velonus scan
        args: ["./", "--severity", "high"]
        language: system
        pass_filenames: false

Sources: README.md

Related Pages

Related topics: Scanner Pipeline, API Backend, Output Formats

CLI Components

Overview

The Velonus CLI is a Typer-based command-line application that provides a unified interface for running security scans on local codebases. The CLI operates in local-only mode without requiring an API connection, making it immediately usable for developers and CI/CD pipelines.

The CLI is structured around command groups that delegate to specialized modules for scanning, authentication, configuration, and PR integration.

Architecture

graph TD
    A["velonus (main.py)"] --> B["scan.app"]
    A --> C["auth.app"]
    A --> D["config.app"]
    A --> E["pr.app"]
    
    B --> F["scanner pipeline"]
    B --> G["formatters"]
    
    G --> H["terminal.py"]
    G --> I["sarif.py"]
    G --> J["json.py"]
    
    C --> K["api_client.py"]
    D --> L["config storage"]
    
    F --> M["NormalizedFinding"]
    M --> G

Command Groups

Root Application

The root Typer application is defined in apps/cli/shield/main.py and registers all command subgroups:

app = typer.Typer(
    name="velonus",
    help="[bold green]Velonus[/bold green] — AI-native AppSec scanner for developers.",
    rich_markup_mode="rich",
    no_args_is_help=True,
    pretty_exceptions_enable=True,
    pretty_exceptions_show_locals=False,
)

Sources: apps/cli/shield/main.py:17-22

Command Registration

Sources: apps/cli/shield/main.py:29-32

The `scan` Command

The scan command is the primary interface for running security analysis on local codebases.

Command Interface

velonus scan [PATH] [OPTIONS]

Sources: apps/cli/shield/commands/scan.py

Severity Levels

Exit Codes

Output Formatters

The CLI supports multiple output formats through a pluggable formatter system.

graph LR
    A["NormalizedFinding"] --> B["Formatter Interface"]
    B --> C["TerminalFormatter"]
    B --> D["SarifFormatter"]
    B --> E["JsonFormatter"]

Terminal Formatter

Renders findings as colored Rich tables with severity badges, file paths, line numbers, rule IDs, and human-readable messages. This is the default format for interactive use.

Output Structure:

┏━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Severity     ┃ Tool     ┃ File         ┃ Line ┃ Rule          ┃ Message                ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩

SARIF Formatter

Generates Static Analysis Results Interchange Format output compatible with GitHub Code Scanning, VS Code SARIF Viewer, and other SAST tooling.

Key transformations:

• Converts rule IDs to PascalCase display names via _rule_id_to_name()
• Generates file:// URIs for directory paths with trailing slashes per SARIF spec §3.14.14

def _rule_id_to_name(rule_id: str) -> str:
    base = rule_id.split("/")[-1]
    return "".join(word.capitalize() for word in base.replace("-", "_").split("_"))

Sources: apps/cli/shield/formatters/sarif.py:58-68

JSON Formatter

Outputs findings as structured JSON for piping into other tools or storing results:

velonus scan ./ --format json | python -m json.tool
velonus scan ./ --format json > scan-results.json

Authentication Module

The auth command manages authentication with the Velonus API backend.

These commands are stubbed in Phase 0 and become functional in Phase 2 when the API backend is live.

Configuration Module

The config command manages local CLI settings stored on disk.

Example configuration:

velonus config set api_url https://api.velonus.dev

Stubbed in Phase 0, fully functional in Phase 2.

PR Integration Module

The pr command provides GitHub PR integration utilities for Phase 3. This module is planned but not yet implemented in Phase 0.

Core API Client

The api_client module in shield/core/ handles communication with the Velonus backend API. It is used by the auth and config modules when API connectivity is required.

Sources: apps/cli/shield/core/api_client.py

Module Structure

apps/cli/shield/
├── main.py                 # Root Typer application
├── commands/
│   ├── __init__.py
│   ├── scan.py            # Security scan command
│   ├── auth.py            # Authentication commands
│   ├── config.py          # Configuration commands
│   └── pr.py              # PR integration (Phase 3)
├── formatters/
│   ├── __init__.py
│   ├── terminal.py        # Rich table output
│   ├── sarif.py           # SARIF format output
│   └── json.py            # JSON output
└── core/
    ├── __init__.py
    └── api_client.py      # Backend API communication

CLI Workflow

sequenceDiagram
    participant User
    participant CLI as velonus scan
    participant Scanner as scanner.pipeline
    participant Formatter
    participant Output

    User->>CLI: velonus scan ./ --severity high
    CLI->>Scanner: Run detectors (secrets, bandit, semgrep, etc.)
    Scanner-->>CLI: List[NormalizedFinding]
    CLI->>Formatter: Format findings based on --format
    Formatter-->>Output: Rendered output (terminal/JSON/SARIF)
    Output-->>User: Display or write to file
    
    alt HIGH/CRITICAL findings
        CLI-->>User: Exit code 1 (CI block)
    else Clean scan
        CLI-->>User: Exit code 0
    end

Usage Examples

Basic Scan

velonus scan ./

Severity Filtered Scan

velonus scan ./ --severity high

Export to SARIF

velonus scan ./ -o results/velonus.sarif --format sarif

Verbose Output

velonus scan ./ --verbose

CI/CD Integration

- name: Velonus security scan
  run: velonus scan . --severity high

Development Guidelines

Per the project's contribution guidelines:

All new CLI components must include matching unit tests. The test suite currently has 367 tests covering scanner wrappers and formatters.

Sources: CONTRIBUTING.md

Related Pages

Related topics: System Architecture, Scanner Pipeline, AI Engine, GitHub PR Reviewer

API Backend

Overview

The Velonus API Backend is a FastAPI-based service layer that provides remote scanning capabilities, AI-powered analysis, GitHub integration, and programmatic access to security findings. Currently planned for Phase 2 of the Velonus roadmap, the API backend will extend the CLI's local-only scanning with cloud-native features including authentication, rate limiting, background processing, and AI-driven remediation suggestions.

Current Status: The API backend is in the planning/stub phase. The CLI is fully functional in local-only mode. Auth, config, and GitHub integration commands are stubbed and will be activated once the backend is live. Sources: README.md

Architecture Overview

graph TD
    Client["Client<br/>(CLI / Web UI)"] --> |"HTTP/REST"| API["API Gateway<br/>(FastAPI)"]
    
    API --> |"Auth"| AuthMW["Auth Middleware<br/>(Clerk OAuth)"]
    API --> |"Rate Limit"| RateMW["Rate Limit Middleware"]
    
    AuthMW --> |"Validated"| Routers["Routers"]
    RateMW --> |"Allowed"| Routers
    
    Routers --> Scans["/scans"]
    Routers --> Findings["/findings"]
    Routers --> GitHub["/github"]
    Routers --> Remediation["/remediation"]
    
    Scans --> ScanSvc["Scan Service"]
    Findings --> ScanSvc
    GitHub --> GitHubSvc["GitHub Service"]
    Remediation --> AISvc["AI Service"]
    
    ScanSvc --> ScanWorker["Scan Worker<br/>(Background)"]
    AISvc --> AIWorker["AI Worker<br/>(Background)"]
    
    ScanWorker --> |"Results"| DB["Database"]
    AIWorker --> |"Analysis"| DB
    
    DB --> Findings

Planned Components

Directory Structure

apps/api/shield_api/
├── main.py                 # FastAPI application entry point
├── middleware/
│   ├── auth.py            # Clerk OAuth authentication
│   └── rate_limit.py      # Request rate limiting
├── routers/
│   ├── scans.py           # Scan management endpoints
│   ├── findings.py       # Finding retrieval endpoints
│   ├── github.py          # GitHub integration endpoints
│   └── remediation.py     # AI remediation endpoints
├── services/
│   ├── scan_service.py    # Scan orchestration logic
│   ├── ai_service.py      # AI analysis and scoring
│   └── github_service.py  # GitHub API integration
└── background/
    ├── scan_worker.py     # Background scan processor
    └── ai_worker.py       # Background AI worker

Sources: README.md

Middleware Layer

Authentication Middleware

The authentication middleware integrates with Clerk for browser-based OAuth authentication. This enables secure API access for authenticated users while maintaining compatibility with the CLI's local-only mode.

The velonus auth command group will provide login/logout/status operations once the backend is live. Sources: README.md

Rate Limiting Middleware

Rate limiting protects the API from abuse and ensures fair resource allocation across users.

Router Modules

`/scans` - Scan Management

Manages scan lifecycle including creation, status tracking, and result retrieval.

#### Request/Response Model

{
  "id": "uuid",
  "status": "pending|running|completed|failed",
  "target_path": "/path/to/project",
  "created_at": "ISO8601 timestamp",
  "completed_at": "ISO8601 timestamp|null",
  "tools_run": ["secrets", "bandit", "semgrep", "pip-audit", "safety"],
  "findings_count": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0,
    "info": 0
  }
}

`/findings` - Finding Retrieval

Provides filtered access to security findings from completed scans.

#### Query Parameters

`/github` - GitHub Integration

Enables GitHub Actions integration and PR inline comments for Phase 3.

This router integrates with the GitHub Service for repository access and comment posting. Sources: README.md

`/remediation` - AI-Powered Fixes

Provides AI-generated fix suggestions for security findings.

Phase 2 features include AI prioritization and exploitability scoring. Phase 3 adds one-click fix suggestions. Sources: README.md

Service Layer

Scan Service

Orchestrates the security scanning pipeline across multiple tools:

The service normalizes findings into the NormalizedFinding model before storage. Sources: packages/scanner/scanner/detectors/secrets.py

AI Service

Provides AI-powered analysis capabilities for Phase 2:

GitHub Service

Handles GitHub API interactions:

Background Workers

Scan Worker

Processes scan jobs asynchronously to avoid blocking HTTP requests.

graph LR
    A[Scan Request] --> B[Queue]
    B --> C[Worker Pool]
    C --> D[Tool 1: Secrets]
    C --> E[Tool 2: Bandit]
    C --> F[Tool 3: Semgrep]
    C --> G[Tool 4: pip-audit]
    C --> H[Tool 5: Safety]
    D & E & F & G & H --> I[Normalize]
    I --> J[Store Results]

AI Worker

Processes AI analysis requests in the background:

Data Models

NormalizedFinding

All scanners output findings in a standardized format:

#### Metadata Schema

Sources: packages/scanner/scanner/detectors/semgrep.py

Output Formats

The API supports multiple output formats for findings:

SARIF Output

SARIF (Static Analysis Results Interchange Format) provides standardized output for integration with security tooling:

{
  "version": "2.1.0",
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "runs": [{
    "tool": {
      "driver": {
        "name": "Velonus",
        "version": "0.1.0"
      }
    },
    "results": [...]
  }]
}

Sources: apps/cli/shield/formatters/sarif.py

Severity Levels

Roadmap Integration

Sources: README.md

CLI vs API Mode

When the API backend is live, users can choose between:

# Local mode (always works)
velonus scan ./my-project

# Cloud mode (requires auth)
velonus auth login
velonus scan ./my-project --remote

Configuration

CLI Configuration

The velonus config command manages local CLI settings:

Environment Variables

Error Handling

CLI exit codes:

Development Guidelines

The API backend follows the project's contribution standards:

• All code must pass ruff check and ruff format --check
• Type checking with mypy --strict --ignore-missing-imports
• Unit tests required for all new endpoints and services
• PRs should be under 400 lines of diff
• No AI-generated placeholder code

Sources: CONTRIBUTING.md

Related Pages

Related topics: Security Detectors, Output Formats, API Backend

Scanner Pipeline

Overview

The Scanner Pipeline is the core orchestration layer in Velonus that coordinates multiple security scanning tools into a unified, concurrent execution framework. It provides a single entry point for running comprehensive security analysis across Python codebases, combining static analysis, secret detection, and dependency vulnerability scanning.

Sources: packages/scanner/scanner/pipeline.py:1-15

Architecture

The pipeline follows a parallel execution model using Python's asyncio framework. Each security tool runs concurrently, with results collected, normalized, and deduplicated before presentation.

graph TD
    A[User Input: Target Path] --> B[ScanPipeline.run]
    B --> C{Is Async Context?}
    C -->|Yes| D[Direct await]
    C -->|No| E[asyncio.run wrapper]
    D --> F[Parallel Scanner Execution]
    E --> F
    F --> G[Secrets Detector]
    F --> H[Bandit Detector]
    F --> I[Semgrep Detector]
    F --> J[pip-audit Detector]
    F --> K[Safety Detector]
    G --> L[RawFinding List]
    H --> L
    I --> L
    J --> L
    K --> L
    L --> M[FindingNormalizer]
    M --> N[DeduplicationFilter]
    N --> O[NormalizedFinding List]
    O --> P[Output Formatters]
    P --> Q[Terminal / JSON / SARIF]

Pipeline Execution Model

Concurrent Execution

The pipeline executes all five detectors in parallel using asyncio.gather(). This approach minimizes total scan time by running independent security checks simultaneously rather than sequentially.

results: list[list[RawFinding]] = await asyncio.gather(
    self._run_detector(secrets_runner, target, verbose),
    self._run_detector(bandit_runner, target, verbose),
    self._run_detector(semgrep_runner, target, verbose),
    self._run_detector(pip_audit_runner, target, verbose),
    self._run_detector(safety_runner, target, verbose),
)

Sources: packages/scanner/scanner/pipeline.py:80-90

Execution Order

Detectors are executed in a fixed order for consistent logging output:

Sources: packages/scanner/scanner/pipeline.py:69-70

Dual Context Support

The pipeline supports both async and sync usage patterns:

# Async context (e.g., API background worker)
pipeline = ScanPipeline()
findings = await pipeline.run(Path("./my-project"), verbose=True)

# Sync context (CLI)
import asyncio
findings = asyncio.run(ScanPipeline().run(Path("./my-project")))

Sources: packages/scanner/scanner/pipeline.py:14-25

Supported Detectors

Secrets Detector

The secrets detector provides dual-layer secret detection:

#### TruffleHog Integration

TruffleHog is the primary secret scanner. It uses commit history analysis and regex-based detector rules to identify verified secrets with high confidence.

Sources: packages/scanner/scanner/detectors/secrets.py:40-60

#### Entropy-Based Fallback

When TruffleHog detects a high-entropy string, it flags potential hardcoded credentials:

message=(
    f"High-entropy string in secret assignment "
    f"(Shannon entropy={entropy:.2f}) — likely a hardcoded credential"
)

Sources: packages/scanner/scanner/detectors/secrets.py:180-185

The entropy scanner walks the target path recursively, skipping non-code directories and binary files:

Skipped directories: .git, node_modules, __pycache__, .venv, venv, .env, dist, build

Sources: packages/scanner/scanner/detectors/secrets.py:95-100

Bandit Detector

Bandit analyzes Python code for common security issues using configurable test sets. It produces findings with severity ratings based on the potential impact of identified issues.

Semgrep Detector

Semgrep runs rule-based analysis using the p/python ruleset:

def scan(self, target: Path) -> list[RawFinding]:
    return self._run_semgrep(target)

Invocation command: semgrep scan --config p/python --json --quiet --metrics=off <target>

Sources: packages/scanner/scanner/detectors/semgrep.py:22-30

#### Availability Check

Semgrep availability is verified via a lightweight version check:

def _semgrep_available(self) -> bool:
    try:
        subprocess.run(
            ["semgrep", "--version"],
            capture_output=True,
            check=False,
            timeout=10,
        )
        return True
    except FileNotFoundError:
        return False

Sources: packages/scanner/scanner/detectors/semgrep.py:55-65

If semgrep is not installed, the detector logs a warning and skips analysis rather than failing the entire scan.

pip-audit Detector

pip-audit scans Python dependencies against the Python Packaging Advisory Database. It extracts CVSS v3 scores to determine severity ratings and identifies available fix versions.

Sources: packages/scanner/scanner/detectors/pip_audit.py:60-85

Safety Detector

Safety provides an additional layer of dependency vulnerability checking, extracting CVE identifiers and advisory information for prioritization.

Sources: packages/scanner/scanner/detectors/safety.py:1-30

Data Flow

graph LR
    A[RawFinding] --> B[FindingNormalizer]
    B --> C[NormalizedFinding]
    C --> D[DeduplicationFilter]
    D --> E[Final Findings]
    
    F[tool+file+line+rule_id] --> G[SHA-256 Hash]
    G --> H[16-char ID]

Raw Finding Structure

Detectors produce RawFinding objects containing raw output from security tools:

@dataclass
class RawFinding:
    tool: str
    rule_id: str
    file: str
    line: int
    severity: str
    message: str
    code_snippet: str
    metadata: dict[str, Any]

Normalized Finding Structure

FindingNormalizer converts raw findings into a canonical format:

@dataclass
class NormalizedFinding:
    id: str  # SHA-256[:16] of tool+file+line+rule_id
    tool: str  # "bandit"|"semgrep"|"secrets"|"pip-audit"|"safety"
    rule_id: str
    cwe: list[str]  # e.g., ["CWE-89"]
    owasp: list[str]  # e.g., ["A03:2021"]
    severity: Severity  # CRITICAL | HIGH | MEDIUM | LOW | INFO
    confidence: Confidence  # HIGH | MEDIUM | LOW
    file: str
    line_start: int
    line_end: int
    code_snippet: str
    message: str
    fix_available: bool = False
    suppressed: bool = False
    first_seen: datetime

Sources: packages/normalizer/models.py:1-50

Deduplication

The DeduplicationFilter removes duplicate findings across scans using deterministic SHA-256 identifiers derived from tool + file + line + rule_id. This ensures consistent identification of the same vulnerability across multiple scans.

Sources: packages/scanner/scanner/pipeline.py:77-78

Severity Classification

Sources: apps/cli/README.md:95-105

Usage Examples

Async Usage

from scanner.pipeline import ScanPipeline
from pathlib import Path

async def scan_project():
    pipeline = ScanPipeline()
    findings = await pipeline.run(Path("./my-project"), verbose=True)
    return findings

Sync Usage

import asyncio
from scanner.pipeline import ScanPipeline
from pathlib import Path

findings = asyncio.run(
    ScanPipeline().run(Path("./my-project"))
)

CLI Usage

# Full scan with all detectors
velonus scan ./

# High severity only (CI gate)
velonus scan ./ --severity high

# JSON output for tooling
velonus scan ./ --format json

# SARIF output for GitHub Security tab
velonus scan ./ --format sarif -o results.sarif

# Verbose timing output
velonus scan ./ --verbose

Sources: README.md:20-40

Exit Codes

Exit code 1 on HIGH/CRITICAL is intentional for CI/CD integration, enabling automated blocking of merges.

Sources: apps/cli/README.md:70-80

Error Handling

Semgrep Exit Code Handling

Semgrep exits with code 1 when findings are present. This is not treated as an error:

Semgrep exits with code 1 when findings are present. This is NOT treated as an error — the JSON output is still fully valid and parsed normally. Exit code 2+ indicates a real error (bad arguments, semgrep crash).

Sources: packages/scanner/scanner/detectors/semgrep.py:22-30

Missing Tool Handling

If a security tool is not installed, the detector logs a warning and returns an empty list rather than failing the scan:

if not self._semgrep_available():
    logger.warning(
        "semgrep not found on PATH — skipping Semgrep analysis. "
        "Install with: pip install semgrep"
    )
    return []

Sources: packages/scanner/scanner/detectors/semgrep.py:32-37

Performance Characteristics

• Parallel execution of all detectors minimizes total scan time
• Timing logging occurs at INFO level when verbose=True, DEBUG otherwise
• Skip patterns exclude common non-code directories to reduce scan scope
• Empty results are handled gracefully, allowing partial scans when tools are unavailable

Related Pages

Related topics: Scanner Pipeline, Output Formats

Security Detectors

Overview

Security Detectors are the core scanning engines within Velonus that identify vulnerabilities, secrets, and insecure code patterns. Each detector wraps an external security tool (TruffleHog, Bandit, Semgrep, pip-audit, Safety) and normalizes its output into a unified RawFinding format. This abstraction layer enables Velonus to run multiple security scanners through a single interface while presenting results in a consistent structure.

The detector system is located in packages/scanner/detectors/ and packages/scanner/scanner/detectors/, with each module handling a specific security tool. Detectors serve as the first stage in Velonus's scanning pipeline, producing raw findings that are later normalized by the FindingNormalizer into the canonical NormalizedFinding model. Sources: packages/scanner/detectors/__init__.py:1

Architecture

graph TD
    A[Scan Request] --> B[Scanner Pipeline]
    B --> C[Secrets Detector]
    B --> D[Bandit Detector]
    B --> E[Semgrep Detector]
    B --> F[pip-audit Detector]
    B --> G[Safety Detector]
    
    C --> H[RawFinding Objects]
    D --> H
    E --> H
    F --> H
    G --> H
    
    H --> I[FindingNormalizer]
    I --> J[NormalizedFinding Objects]
    J --> K[Output Formatters]
    K --> L[Terminal / JSON / SARIF]

Component Overview

Secrets Detector

The Secrets Detector identifies hardcoded secrets, API keys, passwords, and other sensitive credentials in source code. It employs a two-tier detection strategy: primary TruffleHog scanning followed by an entropy-based fallback for generic high-entropy strings.

Detection Pipeline

graph LR
    A[File Input] --> B{TruffleHog Scan}
    B -->|Verified Secrets| C[RawFinding]
    B -->|No Secrets Found| D[Entropy Fallback]
    D -->|High Entropy| E[RawFinding]
    D -->|Low Entropy| F[Skip]

TruffleHog Integration

The detector invokes TruffleHog as the primary secret scanner. When TruffleHog returns results, each finding is parsed and converted to a RawFinding object with the following characteristics:

• Tool: secrets
• Rule ID: trufflehog-{detector-name} (lowercase, spaces replaced with hyphens)
• Severity: CRITICAL (all TruffleHog findings)
• Verification Status: Captured in metadata as verified: bool
• Decoder Information: Extracted from DecoderName in TruffleHog output

Sources: packages/scanner/detectors/secrets.py:1-30

Entropy-Based Fallback

When TruffleHog is unavailable or returns no findings, the detector falls back to an entropy-based scanner (_entropy_scan). This method:

1. Walks the target directory recursively
2. Skips non-code directories (.git, node_modules, __pycache__, .venv, venv, .env, dist, build)
3. Applies regex patterns for known secret types
4. Calculates Shannon entropy for candidate strings
5. Flags strings exceeding the _ENTROPY_THRESHOLD

Sources: packages/scanner/detectors/secrets.py:50-80

File Iteration Logic

The _iter_files method yields scannable source files while excluding:

# Skipped directories
.git, node_modules, __pycache__, .venv, venv, 
.env, dist, build

Finding Structure

Each secrets finding includes:

Sources: packages/scanner/detectors/secrets.py:100-130

Dependency Vulnerability Detectors

Velonus includes two detectors for Python dependency vulnerabilities: pip-audit and Safety. Both analyze dependency manifests (e.g., requirements.txt) and report known CVEs.

pip-audit Detector

The pip-audit detector parses JSON output from the pip-audit tool and converts vulnerabilities into RawFinding objects.

#### Data Extraction

The detector extracts the following fields from pip-audit JSON:

Sources: packages/scanner/scanner/detectors/pip_audit.py:1-50

#### CVSS Score Extraction

The _extract_cvss_score helper parses pip-audit's nested CVSS format:

[{"type": "CVSS_V3", "score": "CVSS:3.1/...", "base_score": 7.5}]

The detector prefers CVSS v3 scores and selects the highest when multiple are present. Sources: packages/scanner/scanner/detectors/pip_audit.py:80-100

#### Message Construction

Finding messages include:

• Package name and version
• Vulnerability ID (preferred CVE alias)
• Fix hint (if available)
• Truncated description (max 200 characters)

Safety Detector

The Safety detector handles both Safety v1 and v2 JSON output formats, which differ significantly in structure.

#### Supported Output Formats

Sources: packages/scanner/scanner/detectors/safety.py:1-50

#### Entry Parsing (v2 Format)

For Safety v2, each vulnerability entry must contain:

required_fields = ["vulnerability_id", "package_name", "analyzed_version"]

Entries missing required fields are skipped with a warning. Sources: packages/scanner/scanner/detectors/safety.py:50-80

#### Parsed Fields

Sources: packages/scanner/scanner/detectors/safety.py:80-120

#### Severity Mapping

CVSS scores are converted to severity levels:

def _cvss_to_severity(cvss_score: float | None) -> str:
    if cvss_score is None:
        return "MEDIUM"  # Default
    elif cvss_score >= 9.0:
        return "CRITICAL"
    elif cvss_score >= 7.0:
        return "HIGH"
    elif cvss_score >= 4.0:
        return "MEDIUM"
    else:
        return "LOW"

Finding Data Models

RawFinding

All detectors produce RawFinding objects with this structure:

@dataclass
class RawFinding:
    tool: str           # "bandit"|"semgrep"|"secrets"|"pip-audit"|"safety"
    rule_id: str        # Scanner-specific rule identifier
    file: str           # Path to file containing the finding
    line: int           # Line number (0 for dependency findings)
    severity: str       # CRITICAL|HIGH|MEDIUM|LOW|INFO
    message: str        # Human-readable description
    code_snippet: str   # Relevant code (redacted for secrets)
    metadata: dict      # Tool-specific additional data

NormalizedFinding

After normalization, findings conform to the canonical NormalizedFinding model:

@dataclass
class NormalizedFinding:
    id: str                          # SHA-256: sha256(tool+file+line+rule_id)[:16]
    tool: str                        # Scanner identifier
    rule_id: str                     # Normalized rule identifier
    cwe: list[str]                   # CWE identifiers (e.g., ["CWE-89"])
    owasp: list[str]                 # OWASP categories (e.g., ["A03:2021"])
    severity: Severity               # Enum: CRITICAL|HIGH|MEDIUM|LOW|INFO
    confidence: Confidence           # Enum: HIGH|MEDIUM|LOW
    file: str                        # File path
    line_start: int                  # Start line
    line_end: int                    # End line
    code_snippet: str                # Redacted code snippet
    message: str                     # Finding message
    fix_available: bool = False      # Whether a fix exists
    suppressed: bool = False         # Whether suppressed
    first_seen: datetime             # Timestamp

Sources: packages/normalizer/models.py:1-50

Extensibility

Adding a new detector follows a consistent pattern:

1. Create a new module in packages/scanner/detectors/
2. Implement the detector class with _scan() method
3. Return RawFinding objects for each finding
4. Include metadata for downstream normalization

Detector Interface Pattern

class BaseDetector:
    def _scan(self, target: Path) -> list[RawFinding]:
        """Main scanning entry point - override in subclasses."""
        raise NotImplementedError
    
    def _iter_files(self, root: Path) -> Iterator[Path]:
        """File iteration with exclusions - reusable utility."""
        ...

Severity Classification

Output Integration

Detectors feed into Velonus's output formatters:

The scanner exits with code 1 when CRITICAL or HIGH findings are detected, enabling use as a CI gate.

Related Pages

Related topics: CLI Components, Scanner Pipeline

Output Formats

Velonus supports multiple output formats for scan results, enabling integration with various security tooling, CI/CD pipelines, and developer workflows. Each format serves a specific use case and targets a different audience.

Overview

The output format system transforms normalized RawFinding objects into format-specific representations. This abstraction allows Velonus to aggregate results from multiple security scanners (Bandit, Semgrep, pip-audit, Safety, TruffleHog) while presenting them consistently regardless of the underlying tool.

Sources: apps/cli/shield/formatters/__init__.py:1

Architecture

graph TD
    A[Scan Command] --> B[Scanner Pipeline]
    B --> C[RawFinding Objects]
    C --> D[Normalizer]
    D --> E[NormalizedFinding]
    E --> F[Output Formatters]
    
    F --> G[Terminal Formatter]
    F --> H[JSON Formatter]
    F --> I[SARIF Formatter]
    
    G --> J[Rich Console Output]
    H --> K[JSON File/Stream]
    I --> L[SARIF 2.1.0 File]

Supported Formats

Sources: apps/cli/README.md:60-65

Terminal Format

The default output format using Rich library for colored, formatted tables with severity badges.

Severity Color Scheme

The terminal formatter uses a consistent color system defined in output.py:

Sources: apps/cli/shield/core/output.py:18-29

Output Table Columns

Terminal Usage

# Default terminal output
velonus scan ./

# Explicit terminal format
velonus scan ./ --format terminal

# Filter by severity
velonus scan ./ --severity high

JSON Format

Machine-readable JSON output suitable for piping into other tools or storing results.

JSON Output Structure

velonus scan ./ --format json

Produces a JSON array of findings with the following schema:

Sources: packages/scanner/scanner/detectors/pip_audit.py:40-52

JSON Usage Examples

# Pretty-print JSON
velonus scan ./ --format json | python -m json.tool

# Save to file
velonus scan ./ --format json > scan-results.json

# Filter by severity
velonus scan ./ --format json --severity high > findings.json

SARIF Format

Static Analysis Results Interchange Format (SARIF 2.1.0) for compatibility with security tooling.

SARIF Specification

Sources: apps/cli/shield/formatters/sarif.py:38-41

Severity Mapping

Sources: apps/cli/shield/formatters/sarif.py:48-54

Rule ID Transformation

SARIF rule IDs are converted to PascalCase display names:

"generic-api-key" → "GenericApiKey"
"secrets/aws-access-key-id" → "AwsAccessKeyId"

Sources: apps/cli/shield/formatters/sarif.py:59-60

Directory URI Handling

Per SARIF spec §3.14.14, directory URIs must end with a trailing slash:

uri = path.as_uri()
return uri if uri.endswith("/") else uri + "/"

Sources: apps/cli/shield/formatters/sarif.py:23-24

SARIF Integration Points

graph LR
    A[Velonus Scan] --> B[SARIF File]
    B --> C[GitHub Security Tab]
    B --> D[VS Code SARIF Viewer]
    B --> E[Other SARIF Tools]

SARIF Usage

# Default SARIF output
velonus scan ./ --format sarif

# Custom output path
velonus scan ./ -o results/velonus.sarif

# Severity filtering (recommended for SARIF)
velonus scan ./ --format sarif --severity high -o findings.sarif

GitHub Actions Integration

- name: Velonus security scan
  run: velonus scan . --sarif -o velonus-results.sarif

- name: Upload to GitHub Security tab
  uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: velonus-results.sarif

Sources: README.md:45-50

Finding Data Model

RawFinding Structure

Each scanner produces RawFinding objects that are normalized before formatting:

RawFinding(
    tool="pip-audit",
    rule_id=vuln_id,
    file=attribution_path,
    line=0,  # Dependency findings are file-level
    severity=severity,
    message=message,
    code_snippet="",
    metadata={
        "package_name": package_name,
        "package_version": package_version,
        "cvss_score": cvss_score,
        "fix_available": bool(fix_versions),
    },
)

Sources: packages/scanner/scanner/detectors/pip_audit.py:40-52

Metadata Fields by Scanner

Sources: packages/scanner/scanner/detectors/semgrep.py:25-35

CLI Options

Global Format Options

Sources: apps/cli/README.md:61-66

Exit Codes

Sources: apps/cli/README.md:97-98

Format Selection Guide

graph TD
    A[Choose Output Format] --> B{Use Case}
    
    B -->|Interactive scanning| C[terminal]
    B -->|CI/CD pipeline| D{Hosting Platform}
    B -->|Tooling integration| E[json]
    
    D -->|GitHub| F[sarif]
    D -->|GitLab| G[json]
    D -->|Azure DevOps| H[sarif]
    
    C --> I[Rich colored tables]
    F --> J[GitHub Security tab]
    E --> K[JSON API processing]

Quick Reference

Related Pages

Related topics: API Backend, Scanner Pipeline

AI Engine

The AI Engine is a core component of Velonus (Phase 2) that provides intelligent prioritization, exploitability scoring, and automated fix generation for security findings. It processes normalized findings from the scanner pipeline and applies AI-driven analysis to help developers focus on the most critical issues first.

Architecture Overview

The AI Engine is structured as a modular system with three primary sub-engines:

graph TD
    A[NormalizedFindings] --> B[Context Engine]
    B --> C[Enriched Findings]
    C --> D[Remediation Engine]
    D --> E[Fix Suggestions]
    C --> F[Exploitability Scoring]
    F --> G[Priority Ranking]
    G --> H[Dashboard / CLI Output]

Sources: packages/ai-engine/context_engine.py

Core Sub-Engines

Context Engine

The Context Engine analyzes security findings in their broader codebase context to determine:

• Reachability analysis — Is the vulnerable code actually executed?
• Data flow analysis — Does user input reach the vulnerable code path?
• Dependency context — Are there mitigating factors in dependencies?

Sources: packages/ai-engine/context_engine.py

Remediation Engine

The Remediation Engine generates specific, actionable fix recommendations based on:

• The vulnerability type and severity
• The affected code location
• Project-specific patterns and conventions

Sources: packages/ai-engine/remediation_engine.py

AI Service

Located in the API layer, the AI Service handles:

• LLM provider integration
• Request batching and rate limiting
• Response parsing and validation

Sources: apps/api/shield_api/services/ai_service.py

Prompt Engineering

The AI Engine uses carefully crafted prompts stored in prompts.py to guide the LLM in:

Sources: packages/ai-engine/prompts.py

Caching Strategy

To optimize performance and reduce API costs, the AI Engine implements a caching layer:

graph LR
    A[Finding Hash] --> B{Cache Lookup}
    B -->|Hit| C[Return Cached Result]
    B -->|Miss| D[Call LLM API]
    D --> E[Store in Cache]
    E --> C

Cache entries are keyed by:

• Finding hash (vulnerability type + file + line)
• Code context snippet
• Project fingerprint

Sources: packages/ai-engine/cache.py

Exploitability Scoring

The AI Engine assigns exploitability scores (1-10) based on:

Sources: packages/ai-engine/context_engine.py

Integration with Scanner Pipeline

The AI Engine receives input from the ScanPipeline after findings have been normalized:

# Pipeline execution order (from packages/scanner/scanner/pipeline.py)
# 0 = secrets, 1 = bandit, 2 = semgrep, 3 = pip-audit, 4 = safety

Normalized findings flow into the AI Engine which:

1. Deduplicates findings using the DeduplicationFilter
2. Enriches each finding with AI-generated context
3. Ranks findings by priority
4. Generates remediation suggestions

Configuration

The AI Engine is configured via the CLI configuration system (velonus config set):

Sources: packages/ai-engine/ai_engine/__init__.py

CLI Integration

The AI Engine features are accessible through Phase 2 CLI commands:

# View AI-generated context for findings
velonus scan ./ --ai-context

# Generate fix suggestions
velonus fix <finding-id>

# Run with AI prioritization
velonus scan ./ --ai-prioritize

Sources: apps/cli/README.md

Development Status

Sources: README.md

API Endpoints

The AI Engine exposes REST endpoints via the API service:

Sources: apps/api/shield_api/services/ai_service.py

Security Considerations

The AI Engine handles sensitive data and implements the following safeguards:

• No code exfiltration — Source code is only processed locally or sent to configured LLM providers
• Input sanitization — All prompts are sanitized before sending to LLM
• Audit logging — All AI requests are logged for compliance
• Cache encryption — Cached results are encrypted at rest

Sources: packages/ai-engine/cache.py

Related Pages

Related topics: API Backend, Scanner Pipeline

GitHub PR Reviewer

Overview

The GitHub PR Reviewer is a planned feature in the Velonus security scanning platform designed to provide automated code review capabilities directly within GitHub Pull Requests. Based on the project roadmap, this feature is designated as Phase 3 — GitHub Integration and is currently marked as Not Started.

Sources: README.md:Phase 3

The Velonus project is a security scanner designed to detect vulnerabilities, secrets, and security issues in Python codebases. The platform currently supports multiple security scanning tools including Bandit, Semgrep, pip-audit, Safety, and TruffleHog for secret detection.

Sources: README.md:Roadmap

Project Architecture

Velonus follows a modular architecture with clear separation between the CLI layer, scanner package, and planned API layer.

graph TD
    A[velonus scan CLI] --> B[packages/scanner]
    B --> C[Detectors]
    C --> D[Secrets Scanner]
    C --> E[Bandit]
    C --> F[Semgrep]
    C --> G[pip-audit]
    C --> H[Safety]
    B --> I[Normalizer]
    I --> J[Formatted Output]
    J --> K[Terminal]
    J --> L[JSON]
    J --> M[SARIF]
    N[Planned: GitHub API] -.-> O[PR Reviewer]

Sources: README.md:Architecture Overview Sources: apps/cli/README.md:Commands

Current Scanner Pipeline

The existing scanner pipeline forms the foundation upon which GitHub PR Reviewer will build. The scanner orchestrates multiple security tools and normalizes their findings into a unified format.

Supported Detectors

Sources: packages/scanner/scanner/detectors/secrets.py:Entropy Scanner Sources: packages/scanner/scanner/detectors/semgrep.py:RULESET Definition

Output Formats

The current implementation supports three output formats that GitHub PR Reviewer can leverage:

Sources: apps/cli/README.md:Output Formats

The SARIF format is particularly relevant for future GitHub integration, as it provides compatibility with GitHub's security tab through the github/codeql-action/upload-sarif action.

- name: Velonus security scan
  run: velonus scan . --sarif -o velonus-results.sarif

- name: Upload to GitHub Security tab
  uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: velonus-results.sarif

Sources: README.md:CI Integration

Planned GitHub PR Reviewer Features

Based on the project roadmap and existing architecture patterns, the GitHub PR Reviewer is expected to provide the following capabilities:

Inline Review Comments

The primary feature will be posting inline comments on pull requests directly where security issues are detected. This follows the pattern of existing GitHub code scanning integrations.

Sources: README.md:Phase 3 — GitHub Integration

Severity-Based Filtering

The existing --severity filtering mechanism will be leveraged to determine which findings trigger PR blocking:

Sources: apps/cli/README.md:Severity Levels

The CLI already exits with code 1 when CRITICAL or HIGH findings are detected, providing a natural CI gate mechanism.

Finding Metadata Structure

The normalized finding format provides the data structure that GitHub PR Reviewer will consume:

RawFinding(
    tool="secrets",           # Source tool
    rule_id="high-entropy-secret",  # Finding type
    file=str(path),           # File path
    line=line_num,            # Line number
    severity="CRITICAL",      # Severity level
    message=str,              # Human-readable message
    code_snippet=str,         # Code context
    metadata={}               # Additional data
)

Sources: packages/scanner/scanner/detectors/secrets.py:RawFinding Creation

Current GitHub Integration Path

While the full GitHub PR Reviewer is not yet implemented, the project provides alternative GitHub integration methods:

GitHub Actions Workflow

For CI/CD integration before Phase 3, users can leverage the existing Velonus CLI in GitHub Actions:

name: Velonus Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install velonus-cli
        run: pip install -e apps/cli
      - name: Run security scan
        run: velonus scan ./ --severity high

Sources: apps/cli/README.md:GitHub Actions

Pre-commit Hook

Security scanning can be integrated into the development workflow using pre-commit hooks:

repos:
  - repo: local
    hooks:
      - id: velonus-scan
        name: Velonus Security Scan
        entry: velonus scan
        args: ["./", "--severity", "high"]
        language: system
        pass_filenames: false

Sources: apps/cli/README.md:Pre-commit hook

Development Guidelines

The project follows strict development standards that will apply to the GitHub PR Reviewer implementation:

Code Quality Requirements

Sources: CONTRIBUTING.md:Code Quality

PR Guidelines

The contributing guidelines establish patterns that GitHub PR Reviewer development must follow:

1. One feature per PR — No bundling unrelated changes
2. Tests required — Every new component needs unit tests
3. Small PRs preferred — Under 400 lines of diff for faster review
4. Target main — All changes merge into main branch
5. No AI-generated placeholder code — Every function must be functional

Sources: CONTRIBUTING.md:PR Guidelines

Commit Message Format

<type>: <short imperative summary>

Types: feat | fix | refactor | test | docs | infra | chore

Sources: CONTRIBUTING.md:Commit Message Format

Project Roadmap

Sources: README.md:Roadmap

Dependencies and Requirements

The scanner already includes several dependencies that would support GitHub PR Reviewer functionality:

Security Scanning Dependencies

• TruffleHog — For secrets detection with decoder support
• Bandit — Python-specific security issues
• Semgrep — Pattern-based security rules
• pip-audit — Python dependency vulnerability scanning

CVSS Integration

The pip-audit and Safety detectors already extract and normalize CVSS scores:

def _extract_cvss_score(cvss_list: Any) -> float | None:
    """Extract the highest CVSS v3 base score from pip-audit's cvss array."""
    # Returns CVSS:3.1/... formatted scores

Sources: packages/scanner/scanner/detectors/pip_audit.py:CVSS Helpers

Summary

The GitHub PR Reviewer is an anticipated Phase 3 feature of the Velonus security scanning platform. While not yet implemented, the foundation is being built through:

1. A robust scanner pipeline with multiple security tool integrations
2. Normalized finding formats suitable for PR comment generation
3. SARIF output for GitHub Security tab compatibility
4. CI/CD integration patterns via GitHub Actions
5. Strict code quality standards for future development

The existing architecture and roadmap indicate that when Phase 3 development begins, the PR Reviewer will leverage the normalized RawFinding data structures to generate inline comments on pull requests, provide one-click fix suggestions, and integrate with GitHub's status check system to block merges when critical vulnerabilities are detected.

Doramagic Pitfall Log

Doramagic extracted 8 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: [bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion)

• Severity: medium
• Finding: Installation risk is backed by a source signal: [bug] Scanner reports test-file findings as production vulnerabilities (no path exclusion). Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/AliAmmar15/Velonus/issues/1

2. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | README/documentation is current enough for a first validation pass.

3. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | last_activity_observed missing

4. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium

5. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | no_demo; severity=medium

6. Security or permission risk: [bug] Same vulnerability reported twice when detected by both Bandit and Semgrep

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: [bug] Same vulnerability reported twice when detected by both Bandit and Semgrep. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/AliAmmar15/Velonus/issues/2

7. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | issue_or_pr_quality=unknown

8. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | hn_item:48143235 | https://news.ycombinator.com/item?id=48143235 | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using velonus with real data or production workflows.

• [[bug] Same vulnerability reported twice when detected by both Bandit and](https://github.com/AliAmmar15/Velonus/issues/2) - github / github_issue
• [[bug] Scanner reports test-file findings as production vulnerabilities (](https://github.com/AliAmmar15/Velonus/issues/1) - github / github_issue
• README/documentation is current enough for a first validation pass. - GitHub / issue