SpectraStrike Documentation

Operational, architecture, SDK, and integration guidance

SpectraStrike User Guide

SpectraStrike Logo

1. Audience and Purpose

This guide is for security operators and platform engineers running SpectraStrike in a local or on-prem Docker environment.

Goals:

2. Runtime Topology

Deployed services:

Optional tool profile:

3. Initial Setup

3.1 Prepare environment

cp .env.example .env
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3.2 Generate certificates

make tls-dev-cert
make pki-internal

Generated artifacts:

3.3 Configure secrets

Set strong credentials in:

4. Start and Operate the Stack

4.1 Start core stack

make up

4.2 Start with tool profile

make up-all

4.3 Centralized logs

make obs-up
make obs-down

4.4 UI-only operations

make ui-build
make ui-up
make ui-logs
make ui-down

Web UI entrypoint:

4.5 Stop stack

make down

5. Exposed Ports

Configured via .env:

All other service ports are internal-only by default.

6. Remote Integration Configuration

SpectraStrike is remote-operator-first.

6.1 Metasploit RPC wrapper

Use env vars:

6.2 Manual Metasploit ingestion

Use env vars:

Run sync command:

PYTHONPATH=src .venv/bin/python -m pkg.telemetry.sync_metasploit_manual
# or explicitly provide tenant context:
PYTHONPATH=src .venv/bin/python -m pkg.telemetry.sync_metasploit_manual --tenant-id tenant-a

6.3 RabbitMQ publisher

Use env vars:

7. Security Controls and Validation

7.1 Baseline checks

make security-check
make policy-check

7.2 Supply-chain gate (local, dockerized)

make sbom
make vuln-scan
make sign-image
make verify-sign
make security-gate
make full-regression

7.3 Firewall controls (host-level)

sudo make firewall-apply
sudo make firewall-egress-apply

7.4 Backup workflows

make backup-postgres
make backup-redis
make backup-all

8. Enterprise Security Notes

Implemented:

In progress:

9. Troubleshooting

9.1 Nginx TLS health fails

9.2 RabbitMQ TLS handshake errors

9.3 Firewall rules break connectivity

9.4 PostgreSQL mTLS connection failures

9.5 Redis mTLS connection failures

10. Sprint 16.7 Host Integration Smoke

Run integration validation against host-installed offensive tooling and telemetry contracts. Sprint 16.8 uses RabbitMQ broker forwarding for VectorVue validation.

export SPECTRASTRIKE_TENANT_ID=tenant-a
make host-integration-smoke

Optional live-path checks (requires configured endpoints):

PYTHONPATH=src .venv/bin/python -m pkg.integration.host_integration_smoke \
  --tenant-id "$SPECTRASTRIKE_TENANT_ID" \
  --check-metasploit-rpc \
  --check-vectorvue

Recommended local federation values for dockerized SpectraStrike -> VectorVue checks:

Optional VectorVue federation gateway smoke:

make vectorvue-rabbitmq-sync

Expected VectorVue integration result during host smoke:

Required host binaries:

The smoke flow preserves Sprint 16/16.5 controls by enforcing tenant-aware telemetry emission and ingestion.

11. BYOT Telemetry SDK

Sprint 16 adds lightweight SDK helpers for BYOT tool authors to emit telemetry in supported schemas.

11.1 Python SDK

Use pkg.telemetry.sdk:

from pkg.telemetry.sdk import build_cloudevent_telemetry

payload = build_cloudevent_telemetry(
    event_type="com.nyxera.tool.scan.v1",
    source="urn:tool:scanner",
    subject="task-1",
    tenant_id="tenant-a",
    data={"operator_id": "alice", "target_urn": "urn:target:ip:10.0.0.5", "status": "success"},
)

11.2 Bash SDK

Source helper script scripts/byot_telemetry_sdk.sh:

source scripts/byot_telemetry_sdk.sh
byot_emit_internal "tool.scan" "scanner-bot" "urn:target:ip:10.0.0.5" "success" "tenant-a" '{"ports":[22,443]}'

12. Operational References

13. Known QA Constraint (Sprint 9.8)

In restricted network environments, Web UI dependency bootstrap may fail due to DNS resolution issues against the npm registry.

Observed command outcomes:

When this occurs: