NullSec-RedTeam-AI

Authorization-first, MCP-governed security execution for explicitly approved environments.

NullSec-RedTeam-AI is a single-host control plane for governed security-tool workflows. It records a campaign’s approved scope, actor context, policy decision, durable job lifecycle, audit trail, and evidence reference before a worker is allowed to execute a job. Its default posture is sandbox-required and fail-closed: a required sandbox never degrades to host execution.

Use only with explicit written authorization. This project is early-stage security software, not an autonomous red-team system, a substitute for an engagement agreement, or a multi-tenant service. Run it in isolated test environments or on assets you are expressly authorized to assess.

Why NullSec?

Related MCP server: ContextBridge

Architecture at a Glance

A user or MCP client reaches the transport layer only after authentication and caller-context construction. The campaign policy engine decides whether a typed request is in scope. The durable job store coordinates leases and audit events; a lease-aware worker can then request a least-privilege sandbox run. AURA remains above the execution boundary, with a separate evidence-review stage.

The source-controlled Mermaid diagram is available at docs/assets/control-plane-architecture.mmd. Read the architecture rationale in ADR-001.

Quick Start for Safe Local Development

The development workflow uses mocks and simulated fixtures; it does not install, download, or execute security tools.

git clone https://github.com/Panda1847/NullSec-RedTeam-AI.git
cd NullSec-RedTeam-AI
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'

pytest
ruff check .

For local API-development work, use project-local state, a non-production token, and loopback binding only.

mkdir -p .nullsec/logs .nullsec/jobs
export NULLSEC_LOG_DIR="$PWD/.nullsec/logs"
export NULLSEC_JOB_DIR="$PWD/.nullsec/jobs"
export API_TOKEN="local-development-token"
export NULLSEC_LOCAL_ACTOR_ID="local-operator"
export NULLSEC_LOCAL_ACTOR_ROLES="operator"

hexstrike-server --host 127.0.0.1 --port 8888

The service rejects non-loopback binding unless NULLSEC_ALLOW_NON_LOOPBACK=true is explicitly set. Treat that setting as a deployment change requiring an authenticated reverse proxy and an approved network policy.

Safe Campaign Flow

A campaign records authorization and scope. The following loopback-only example creates a campaign record; it does not run a tool.

curl --request POST http://127.0.0.1:8888/api/campaigns \
  --header "Authorization: Bearer $API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "campaign_id": "local-demo-001",
    "allowed_targets": ["127.0.0.0/8"],
    "allowed_capabilities": ["passive"],
    "starts_at": "2026-08-18T09:00:00+00:00",
    "ends_at": "2026-08-18T17:00:00+00:00"
  }'

Job submission requires that campaign, a supported capability tier, and an idempotency key. With the default sandbox_required mode, a job remains safe to queue but fails closed at execution unless an operator has supplied a reviewed immutable image and rootless runner configuration.

curl --request POST http://127.0.0.1:8888/api/tools/execute \
  --header "Authorization: Bearer $API_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'X-Trace-Id: local-demo-trace-001' \
  --data '{
    "tool": "nmap",
    "target": "127.0.0.1",
    "options": "-sV",
    "campaign_id": "local-demo-001",
    "capability": "passive",
    "idempotency_key": "local-demo-request-001"
  }'

Do not place bearer tokens in shell history, source control, screenshots, or CI logs.

AI Security Lab

The AI Security Lab distinguishes a simulation from an actual provider evaluation. Its default output has mode: simulation and status: not_evaluated; it does not claim a model is vulnerable, resistant, or scored. Provider evaluation stays unavailable until an organization supplies a consented adapter, a versioned dataset, protected credentials, evidence storage, and a scoring method.

ai-lab --list
ai-lab --model consented-test-model --technique PROMPT_INJECTION --mode simulation

The project deliberately does not generate bypass payloads. Any provider-backed assessment should use a reviewed, versioned dataset in an isolated environment.

Quality Gates

Every contribution should satisfy test, code-quality, security, packaging, and review expectations before release.

The public workflow covers tests with focused coverage, Ruff linting, focused type checking, static security analysis, dependency auditing, and PEP 517 package builds. The quality-gate diagram source is docs/assets/quality-gates.mmd.

Project Status and Roadmap

See ROADMAP.md for the maintained implementation sequence and IMPLEMENTATION_SUMMARY.md for the 7.1 modernization record.

Documentation

Contributing

Contributions must preserve the authorization-first posture. New integrations need a typed request model, risk tier, capability scope, safe execution profile, deterministic tests, and an evidence parser or documented limitation. Do not add arbitrary shell execution, unbounded option strings, live-target tests, credentials, target inventories, or generated scan artifacts.

Open a design issue or propose an architecture decision record before broad changes. Review CONTRIBUTING.md first, and use SECURITY.md instead of public issues for vulnerability reports.

License

This project is licensed under the MIT License. The license does not grant authorization to assess a system. Operators remain responsible for applicable law, contracts, organizational policy, written authorization, and engagement constraints.