BADASS Local Runner

Securely connect private AI endpoints to BADASS Cloud for authorized behavioral security testing.

What it is

The BADASS Local Runner (badass-runner) connects AI endpoints inside your private network to BADASS Cloud without requiring them to be publicly accessible.

The runner establishes an outbound connection, executes authorized behavioral security tests locally, and returns the messages sent to the endpoint and the replies received to the BADASS dashboard, with authentication headers stripped and recognised secrets redacted. It supports token-based registration, configurable endpoint access, CI and headless environments, and strict protocol validation.

The runner reports observed endpoint behavior. It does not claim that an upstream gateway enforced a policy unless that enforcement is independently verified.

Why it exists

Many AI systems under test run behind:

• corporate VPNs
• private cloud networks
• localhost development environments
• firewalls that block inbound connections

BADASS Cloud cannot reach these endpoints directly. The connector solves this by running inside your network and pulling jobs from the cloud rather than receiving inbound traffic.

Your endpoint never needs a public IP address. For Mode-2 protected operations, credentials provisioned into the runner-local store never leave that machine.

Requirements

• Python 3.11 or later
• Network access to https://badass-sec.com (outbound HTTPS only)
• The AI endpoint you want to test (reachable from the machine running the connector)

Installation

From PyPI (recommended)

pip install badass-runner

See PyPI release history for available versions.

From source

git clone https://github.com/DKB8man/badass-connector
cd badass-connector
pip install .

Verify

badass-runner --version

See docs/install.md for detailed install options, virtual environment setup, and environment variable reference.

BADASS Cloud supports only the latest published connector. Each connector release therefore requires operators to run pipx upgrade badass-runner; outdated connectors are hard-rejected before job dispatch rather than allowed to produce qualified results with a compatibility warning.

Quick start

1. Create a registration token

Open Connect Runner in BADASS Cloud, name the connector, and create its one-time account-owned registration token.

2. Register and start the connector

badass-runner start \
  --server-url https://badass-sec.com \
  --token badass_reg_YOURTOKEN \
  --name my-private-ai-server

The one-time token is exchanged for a permanent local runner credential. The connector runs in the foreground, sends a heartbeat to the cloud every 30 seconds, and polls for harness jobs assigned to it. Later starts use the saved credential:

badass-runner start

Press Ctrl-C or run badass-runner stop (from another terminal) to shut it down.

3. Check status

badass-runner status

Testing private and local AI apps

The connector targets any HTTP endpoint that accepts a text message and returns a text reply — the same interface used by most chat-completion, agent, and RAG APIs.

Typical configuration in the BADASS Cloud dashboard:

For Mode-2 protected operations, provision credentials into the connector's local OS-keyring-backed store:

badass-runner cred set --target-ref TARGET_ID --context admin --auth-type bearer
badass-runner cred list

The cloud sends only opaque credential references in schema-3 enforcement plans. The runner resolves them locally at execution time and uploads the messages sent to the endpoint and the replies received, with authentication headers stripped and recognised secrets redacted. Credential values are never sent to the cloud. See Where credentials live and Runner-local credentials.

Token-based registration for headless systems

CI pipelines and headless systems use the same account-owned one-time registration-token flow:

badass-runner start \
  --server-url https://badass-sec.com \
  --token    badass_reg_YOURTOKEN \
  --name     my-ci-runner

The token is consumed on first use and replaced with a long-lived runner credential stored in the local config file.

Where credentials live

All connector state is stored in ~/.badass-runner/ (overridable with $BADASS_RUNNER_HOME):

~/.badass-runner/
  config.json   # runner_id, runner_token, server_url, runner_name
  runner.pid    # PID of the running connector process

config.json is written with permissions 0600 (owner read/write only). It contains:

• server_url — the BADASS Cloud base URL
• runner_name — a human-readable label you chose
• runner_id — your runner's UUID assigned by the cloud
• runner_token — the long-lived bearer token used to authenticate job polls and result uploads

Your API keys and endpoint credentials are never written to config.json. For Mode 2, you provision them directly on the runner host with badass-runner cred set; values are stored in the OS keyring, while a separate mode-0600 JSON index contains only target/context references and auth metadata. Use badass-runner cred list to inspect that metadata and badass-runner cred remove to delete a local credential. Secrets are entered through a hidden prompt, standard input, or a local env-file—never through command-line arguments.

Mode 1 remains separate: cloud-direct testing uses credentials held by BADASS Cloud for cloud-side requests. The local-only guarantee above applies to runner-local Mode-2 credentials.

What data is uploaded

When the connector completes a harness test, it uploads to BADASS Cloud:

What is never uploaded

The connector is designed so the following data never leaves your machine:

See docs/security-model.md for the full technical description of the redaction layer.

Commands

Environment variables

Local status server

While running, the connector exposes a read-only HTTP status endpoint on localhost at port 7890 (configurable via --port or BADASS_STATUS_PORT). This is not accessible from outside the machine. It is intended for local monitoring integrations.

Security

See SECURITY.md for how to report vulnerabilities and our data handling commitments.

See docs/security-model.md for a full description of what data the connector handles, what it redacts, and what it uploads.

License

See LICENSE file.