nself pentest-kit

Run structured penetration tests against your nSelf stack, generate machine-readable reports, and apply recommended mitigations — all from the CLI.

Quick start

# Run the full scan against the local stack
nself pentest-kit scan

# Generate a PDF report from the last scan
nself pentest-kit report --format pdf --out ./security-report.pdf

# Auto-apply safe mitigations
nself pentest-kit mitigate --auto

Synopsis

nself pentest-kit <SUBCOMMAND> [FLAGS]

Description

nself pentest-kit is the built-in security audit surface for nSelf. It runs a structured set of attack vectors across auth, storage, network, database, API, and plugin surfaces and produces findings categorized by severity (CRITICAL / HIGH / MEDIUM / LOW / INFO).

The kit is used internally by the SIEGE adversarial QA step in every nSelf release cycle and is also available for customer-facing security audits. All findings reference the CWE and OWASP identifiers where applicable.

Security scans only read from your stack — they never modify production data or inject persistent payloads. Destructive tests (SQLi writes, RCE probes) require the --allow-destructive flag and only run against non-production environments.

Scan coverage

Subcommands

nself pentest-kit scan

Run the full scan suite. By default targets the local stack. Pass --target to scan staging or production (read-only tests only against production).

# Local scan
nself pentest-kit scan

# Staging scan
nself pentest-kit scan --target staging

# Limit to specific categories
nself pentest-kit scan --only auth,network,api

# Include destructive probes (non-production only)
nself pentest-kit scan --allow-destructive --target staging

Scan output is stored at ~/.nself/pentest/<timestamp>.json and summarized to stdout.

# Example summary output
# SEVERITY   COUNT
# CRITICAL   0
# HIGH       1   → Hasura introspection enabled on staging
# MEDIUM     3
# LOW        7
# INFO       12
#
# Full results: ~/.nself/pentest/2026-05-07T14-22-00.json

nself pentest-kit report

Generate a formatted report from the most recent scan (or a specific scan file). Supports PDF, HTML, Markdown, and JSON output formats.

# PDF (default)
nself pentest-kit report --format pdf --out ./report.pdf

# Markdown (good for GitHub issues or Notion)
nself pentest-kit report --format md --out ./report.md

# From a specific scan file
nself pentest-kit report --from ~/.nself/pentest/2026-05-07T14-22-00.json --format html --out ./report.html

nself pentest-kit mitigate

Apply mitigations for findings from the most recent scan. Safe mitigations (config changes, flag toggles, env var updates) are applied automatically with --auto. Findings that require code changes are printed as actionable instructions.

# Review what mitigations are available (dry run)
nself pentest-kit mitigate --dry-run

# Apply all safe mitigations automatically
nself pentest-kit mitigate --auto

# Apply mitigations for a specific severity tier and above
nself pentest-kit mitigate --auto --min-severity high

Example: disabling Hasura introspection automatically:

# Finding: HASURA_GRAPHQL_ENABLE_INTROSPECTION=true on staging
# Mitigation:
nself pentest-kit mitigate --auto
# ✓ Applied: HASURA_GRAPHQL_ENABLE_INTROSPECTION → false (staging)
# ✓ Auth service reloaded

Flags

Examples

Nightly CI security gate

nself pentest-kit scan --target staging --skip destructive
# Exit code 1 if any CRITICAL or HIGH findings
nself pentest-kit report --format json | jq '.findings | map(select(.severity == "CRITICAL" or .severity == "HIGH")) | length'

Customer-facing audit package

nself pentest-kit scan
nself pentest-kit report --format pdf --out ./audit-$(date +%Y-%m-%d).pdf
nself pentest-kit report --format md  --out ./audit-$(date +%Y-%m-%d).md

Exit codes

• 0 — scan complete, zero CRITICAL findings
• 1 — one or more CRITICAL findings
• 2 — scan could not complete (network error, stack not running)
• 3 — invalid arguments

Related

• nself doctor — configuration health check (non-adversarial)
• nself audit — user activity and access audit log