Metadata-Version: 2.4
Name: apisec-code-bolt
Version: 0.1.8
Summary: Static analysis probe for extracting architectural metadata from codebases
Project-URL: Homepage, https://apisec.ai
Project-URL: Documentation, https://docs.apisec.ai/code-bolt
Project-URL: Repository, https://github.com/apisec-inc/apisec-code-bolt
Author-email: APIsec <engineering@apisec.ai>
License: Proprietary
Keywords: api,security,static-analysis,vulnerability
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: javalang>=0.13.0
Requires-Dist: libcst>=1.1.0
Requires-Dist: networkx>=3.2
Requires-Dist: pathspec>=0.12.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: tree-sitter-c-sharp>=0.23
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter-ruby>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.23
Requires-Dist: typing-extensions>=4.9.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: semgrep
Requires-Dist: semgrep>=1.50.0; extra == 'semgrep'
Description-Content-Type: text/markdown

# 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`](https://pypi.org/project/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:

```bash
# 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

```bash
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`](https://docs.astral.sh/uv/), which fetches a
> compatible interpreter automatically:
>
> ```bash
> 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

```bash
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 `###-###`):

```bash
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:

```bash
export APISEC_REGISTRATION_CODE=123-456
```

### 2. Authenticate

Store your APIsec API key so uploads are authorized:

```bash
# 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

```bash
# 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

```bash
# 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:

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

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

```yaml
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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).

```bash
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).

```bash
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

```bash
# 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

```bash
pytest
```

### Type Checking

```bash
mypy src/apisec_code_bolt
```

### Linting & Formatting

```bash
ruff check .
ruff format --check .
```

## 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.
