apisec-code-bolt

Static analysis probe for extracting architectural metadata from codebases.

Overview

apisec-code-bolt analyzes source code to extract:

• Routes/Endpoints — HTTP routes, parameters, request/response types
• Data Flows — How data moves from entry points to sinks
• Authentication — Auth schemes, dependencies, role requirements
• Integrations — External services, databases, APIs
• Dependencies — Package dependencies and versions

The output is a structured manifest that can be uploaded to the APIsec cloud for vulnerability analysis. Raw source code never leaves your environment.

Requirements

• Python 3.11 or newer (3.11 and 3.12 are supported). Check with python --version.
• No JDK, Node, Ruby, or .NET runtime required — all parsers are pure-Python (Java via javalang, C#/JS/TS/Ruby via tree-sitter grammars). You can analyze a Java or Ruby project without those toolchains installed.

Installation

The CLI is published on PyPI as apisec-code-bolt.

Recommended: isolated install (pipx or uv)

Installing a CLI into an isolated environment avoids dependency conflicts with other tools and sidesteps system-Python issues:

# Using pipx
pipx install apisec-code-bolt

# Or using uv (also handles the Python version for you)
uv tool install apisec-code-bolt

Plain pip

pip install apisec-code-bolt

On an older or mismatched Python? If pip install fails with a requires-python error, your default python is older than 3.11. The simplest fix is uv, which fetches a compatible interpreter automatically:

uv tool install apisec-code-bolt          # install the CLI, or
uv run --python 3.12 apisec-code-bolt ...  # run ad hoc under 3.12

Verify the install

apisec-code-bolt --version

Getting Started (end to end)

A full run is three steps: register → authenticate → analyze.

1. Register (first run only)

The first time you run the CLI it asks for the registration code APIsec provided during onboarding (format ###-###):

apisec-code-bolt analyze .    # prompts: "Please enter code (###-###)"

For non-interactive environments (CI, scripts), supply it via the environment instead of typing it at a prompt:

export APISEC_REGISTRATION_CODE=123-456

2. Authenticate

Store your APIsec API key so uploads are authorized:

# Interactive (prompts for the key)
apisec-code-bolt auth

# Or pass the key directly
apisec-code-bolt auth sk_live_abc123...

# Confirm you're authenticated
apisec-code-bolt auth --check

3. Analyze

# Analyze the current project and upload the manifest to the cloud
apisec-code-bolt analyze .

On a successful upload the CLI prints a "View Results in APIsec" panel with a direct link to your results in the console.

Working offline / inspecting the manifest

# Analyze and save the manifest locally, no upload
apisec-code-bolt analyze . --output manifest.json --no-upload

# Analyze but write nothing — just print a summary (great for a first look)
apisec-code-bolt analyze . --dry-run

# Emit manifest JSON to stdout for piping into other tools
apisec-code-bolt analyze . --stdout --no-upload | jq .

# Give the extractor framework hints
apisec-code-bolt analyze . --frameworks fastapi,sqlalchemy

Supported Languages & Frameworks

Language	Frameworks
Python	FastAPI, Flask, Django, GraphQL (Strawberry / Graphene / Ariadne), Celery, Click, Prefect
Java	Spring Boot, Micronaut, JAX-RS (Quarkus), GraphQL (Spring for GraphQL / graphql-java-kickstart)
JavaScript / TypeScript	Express, Fastify, NestJS, GraphQL (NestJS GraphQL / TypeGraphQL)
Ruby	Rails, Grape, Sinatra, GraphQL (graphql-ruby)
C# / .NET	ASP.NET Core, legacy ASP.NET (MVC/Web API), WCF, gRPC, Refit

Framework coverage is validated end-to-end against real-world repositories in the benchmark suite (benchmark/).

Configuration

Scaffold a config file with sensible defaults:

apisec-code-bolt init            # writes .surface.yaml

.surface.yaml in your project root is picked up automatically:

analysis:
  file_discovery:
    exclude_patterns:
      - "tests/**"
      - "**/migrations/**"
    max_files: 10000

  data_flow:
    mode: inter_procedural
    max_depth: 10

cloud:
  enabled: true
  api_url: https://api.apisec.ai

output:
  format: json

Commands

Global options (before the subcommand): --version, -v/--verbose, -q/--quiet, --debug, --log-format [text|json].

analyze

Analyze a codebase and generate/upload a manifest.

apisec-code-bolt analyze [PATH] [OPTIONS]

Options:
  -o, --output FILE     Save manifest to file instead of uploading
  --no-upload           Skip uploading to cloud (implies --output if not set)
  --cloud-url TEXT      Reasoning engine URL (legacy direct connection, local dev)
  --api-key TEXT        Override stored API key
  --api-url TEXT        Override stored API URL
  --reasoning-url TEXT  Reasoning engine URL (if different from API URL)
  --format [json|yaml]  Output format
  --config FILE         Path to configuration file
  --frameworks TEXT     Comma-separated framework hints
  --exclude TEXT        Glob patterns to exclude (repeatable)
  --max-files INTEGER   Maximum files to analyze
  --timeout INTEGER     Analysis timeout in seconds
  --dry-run             Analyze and print a summary; write/upload nothing
  --stdout              Write manifest JSON to stdout (for pipelines)

auth

Authenticate with the APIsec cloud.

apisec-code-bolt auth [API_KEY] [OPTIONS]

Options:
  --api-url TEXT  APIsec API URL
  --check         Check if already authenticated
  --logout        Remove stored credentials

init

Scaffold a .surface.yaml configuration file.

apisec-code-bolt init [OPTIONS]

Options:
  -o, --output FILE  Output file path (default: .surface.yaml)
  --force            Overwrite an existing file

validate

Validate a manifest file against the schema.

apisec-code-bolt validate MANIFEST_FILE

answer

Answer verification queries (for air-gapped environments where the manifest was uploaded separately and the cloud generated questions).

apisec-code-bolt answer [OPTIONS]

Options:
  -q, --questions FILE  Input questions file (JSON) [required]
  -o, --output FILE     Output answers file
  -r, --repo DIRECTORY  Repository path
  --timeout INTEGER     Query timeout in seconds

telemetry

Manage anonymous usage telemetry (opt-out; on by default, disable any time with telemetry off; never includes code, paths, or credentials).

apisec-code-bolt telemetry on|off|status

Architecture

apisec-code-bolt/
├── cli/                 # Command-line interface
├── core/                # Types, config, manifest schema
├── parsing/             # Language-specific parsers
│   ├── python/          # LibCST-based Python parser
│   └── jvm/             # Java via the pure-Python javalang library
├── frameworks/          # Framework plugins
│   ├── python/          # FastAPI, Flask, Django, GraphQL, Celery, Click, Prefect
│   ├── java/            # Spring Boot, Micronaut, JAX-RS, GraphQL
│   ├── js/              # Express, Fastify, NestJS, GraphQL
│   ├── ruby/            # Rails, Grape, Sinatra, GraphQL
│   └── dotnet/          # ASP.NET Core, legacy ASP.NET, WCF, gRPC, Refit
├── analysis/            # Call graph, data flow
├── fingerprinting/      # Integration detection
├── query/               # Query API executor
└── cloud/               # Cloud communication

Development

Setup

# Clone and install in development mode
git clone https://github.com/apisec-inc/apisec-code-bolt.git
cd apisec-code-bolt
pip install -e ".[dev]"

Running Tests

pytest

Type Checking

mypy src/apisec_code_bolt

Linting & Formatting

ruff check .
ruff format --check .

Publishing a release (maintainers)

The CLI is published to PyPI by the Publish to PyPI GitHub Action. Merging to build does NOT publish — the workflow only runs on workflow_dispatch or a published GitHub Release, and it builds from whatever ref it runs on.

Prerequisites (one-time): the PYPI_API_TOKEN repository secret must be set (Settings → Secrets and variables → Actions).

1. Bump the version. Edit version in pyproject.toml (single source of truth; --version reads it via package metadata). PyPI rejects re-uploads of an existing version, so the number must be higher than the current PyPI release. Open a PR and merge it to build.

2. Publish — dispatch the workflow (the standard path we use): Actions → Publish to PyPI → Run workflow → select branch build.

   gh workflow run "Publish to PyPI" --ref build
   

   Alternative: publish via a GitHub Release

   New release → create tag vX.Y.Z → set Target: build (it defaults to the default branch; only build has the bumped version) → Publish. This fires the same workflow via release: [published].

   gh release create vX.Y.Z --target build --title "vX.Y.Z" --notes "…"
   

3. Verify. Confirm the new version appears on PyPI, then upgrade an install:

   uv tool upgrade apisec-code-bolt   # or: pipx upgrade apisec-code-bolt
   

Always release from build after the version bump has merged there — releasing from a ref that still carries the old version will fail the PyPI upload.

Privacy

apisec-code-bolt is designed with privacy as a core principle:

• No raw code egress — Source code never leaves your environment
• Metadata only — The manifest contains structural information, not code
• Outbound only — Only makes outbound HTTPS calls to upload manifests
• Air-gapped support — Can run completely offline with file-based workflow

License

Proprietary. Copyright © APIsec.