Cloud application pentesting

nuguard pentest runs conventional HTTP/HTTPS application pentesting against a target you're explicitly authorized to test:

nuguard pentest \
  --target https://staging.example.com \
  --acknowledge-authorization

This is different from nuguard redteam, which targets adversarial AI behavior, not conventional HTTP vulnerabilities.

Authorization

Only run this against applications you own or have documented permission to test. The command refuses to run without --acknowledge-authorization.

That flag doesn't grant permission — it just records that an operator made an explicit decision, so a copied command or CI config can't trigger a scan by accident.

Nuclei engine

The first engine is ProjectDiscovery Nuclei. NuGuard requires Nuclei 3.11.1+ and checks that the installed build supports every safety option the integration uses.

NuGuard doesn't install or update Nuclei — install it yourself, then put it on PATH or pass --nuclei-binary.

NuGuard does auto-fetch the official Nuclei template set once, the first time it's missing: if a scan fails with Nuclei's "no templates provided for scan" error and no --templates-dir was pinned, NuGuard runs one untimed nuclei -update-templates and retries the scan once. That's the only network call the integration makes for templates — the scan itself always runs with -disable-update-check and never fetches templates mid-scan. Pin --templates-dir to a trusted, pre-populated directory to skip this auto-fetch entirely.

Default safety measures:

  • HTTP-only templates (no code, JavaScript, headless, file, DNS, TCP, workflow, SSL, WebSocket, or WHOIS template types);
  • signed templates only, no unsigned ones;
  • no OAST or Interactsh;
  • no fuzzing, denial-of-service, brute-force, default-login, or intrusive tags, and no DAST pass;
  • no redirect following;
  • no stdin targets;
  • no automatic update checks or template downloads mid-scan;
  • no inherited cloud-upload activation;
  • no raw request, response, curl-command, or template-body retention;
  • a closed set of scanner arguments;
  • bounded rate, concurrency, retries, request timeout, whole-scan timeout, response size, JSONL line size, and total output size.

Two flags relax this, each opt-in with a clear tradeoff:

  • --allow-active-fuzzing — adds a second Nuclei pass using -dast and stops excluding fuzz/intrusive tags. This sends significantly more, and more intrusive, requests. Only use it against targets you're authorized to actively fuzz.
  • --allow-headless-browser — turns on Nuclei's headless-browser (JS-running) templates. First use triggers an unmanaged ~120 MB Chromium download from storage.googleapis.com. NuGuard refuses to run this flag as root.

Both are off by default; set them per invocation or via pentest.allow_active_fuzzing / pentest.allow_headless_browser in nuguard.yaml.

NuGuard also always runs a bundled template pass alongside the standard corpus (--bundled, on by default; --no-bundled disables it). It covers generic injection and access-control issues (SQLi/NoSQLi login bypass, error-based SQLi, command injection, LDAP injection, JWT cookie flags, open redirects, reflected XSS, SSTI, CRLF injection, path traversal, and credentialed CORS), plus exposed configuration, environment files, Git metadata, directory listings, stack traces, TRACE, and missing clickjacking protection.

The bundled pass is meant for explicitly authorized sandbox/staging deployments. Some of its templates send bounded proof-of-vulnerability payloads — they might obtain an otherwise-unauthorized test session or run a harmless printf, but they never retain sessions, write application data, reach external services, brute-force credentials, or attempt denial of service. Use --no-bundled if even these bounded checks fall outside your approved test plan.

Bundled templates are auto-signed locally the first time they run — no manual nuclei -sign step needed. They're cached in ~/.cache/nuguard/pentest-templates, with the signing key at ~/.config/nuguard/nuclei-signing-key.pem. If auto-signing fails for any reason, NuGuard logs a warning, skips the bundled pass, and continues the rest of the scan — it never fails the whole run over this.

A custom --templates-dir runs as its own additional pass. Its templates must already be signed (nuclei -sign -t <dir>), since unsigned templates are always rejected.

NuGuard's parent-process watchdog enforces the whole-scan deadline, not an engine-specific CLI option. The default is 45 minutes (scan_timeout / --scan-timeout, 2700 seconds), giving multi-pass scans (standard + bundled + optional DAST + optional custom templates) real headroom. Raise it further if --allow-active-fuzzing drives DAST against a large OpenAPI document (see below).

Live progress (matched/requests/errors/percent) logs every --stats-interval seconds (default 5) as each pass runs, not just at the end.

Target scope

Only explicit http:// and https:// URLs are accepted.

The target validator rejects:

  • credentials embedded in URLs;
  • credential-like query parameters;
  • URL fragments and control characters;
  • loopback addresses;
  • link-local addresses;
  • multicast and reserved ranges;
  • cloud metadata-service addresses;
  • Kubernetes control-plane hostnames;
  • mixed DNS answers containing any blocked address;
  • private addresses, unless --allow-private is supplied;
  • more than 50 input targets.

--allow-private permits private RFC1918 and unique-local targets, but never loopback, link-local, metadata-service, multicast, or reserved targets.

Public scans also turn on Nuclei's local-network restriction. That's only skipped when the operator explicitly passes --allow-private.

Profiles

The default safe profile scans low, medium, high, and critical findings.

The standard profile also includes informational templates. Both keep the same protocol and intrusive-template restrictions.

nuguard pentest \
  --target https://staging.example.com \
  --profile standard \
  --acknowledge-authorization

Multiple targets

Repeat --target:

nuguard pentest \
  --target https://app.example.com \
  --target https://api.example.com \
  --acknowledge-authorization

Or supply a UTF-8 target file:

# authorized-targets.txt
https://app.example.com
https://api.example.com
nuguard pentest \
  --target-file authorized-targets.txt \
  --acknowledge-authorization

Target from nuguard.yaml

If neither --target nor --target-file is given, nuguard pentest falls back to the shared target: url: value in nuguard.yaml (the same block behavior and redteam use):

nuguard pentest \
  --config nuguard.yaml \
  --acknowledge-authorization

--target/--target-file still win over the config file if both are given.

OpenAPI-driven DAST input

--allow-active-fuzzing's DAST pass fuzzes whatever it's given. A plain target URL like https://api.example.com/chat has no query, path, or body parameters, so DAST has nothing to work with on its own. NuGuard instead feeds that pass a real OpenAPI document (-input-mode openapi) so Nuclei can build one request per operation, including the JSON body, and fuzz every field.

NuGuard uses an explicit file if you supply one. Otherwise it merges these sources into one request inventory:

  1. An explicit file: --openapi-spec ./openapi.json.
  2. The target's own live spec, probed at /openapi.json and similar paths (--live-openapi, on by default; --no-live-openapi disables it).
  3. A document synthesized from --config's SBOM API_ENDPOINT nodes — their discovered method, path, and request-body field types — used when the target serves no live spec. Controlled by --use-sbom-endpoints (also pentest.use_sbom_endpoints), on by default whenever sbom: is configured at all.

Every source gets constrained to the validated target before use: its servers entry is rewritten to the target's own origin and mount path, so an untrusted live document can never redirect the scanner elsewhere. With prioritized selection, unresolved input hints get mined first; operations that still have no named input are left out of the final DAST document unless explicitly included. Findings map back to selected operations relative to the target's path prefix, including mounts like /app.

nuguard pentest \
  --config nuguard.yaml \
  --acknowledge-authorization \
  --allow-active-fuzzing \
  --openapi-spec ./openapi.json

An SBOM isn't required when the target serves its own OpenAPI/Swagger document (source 2 above) — the live spec is used automatically. It's still useful as a fallback for deployments that disable their docs routes, and separately from DAST input, for auto-upgrading type: basic authentication to a discovered login_flow (see Authentication, below).

Configuring pentest via nuguard.yaml

Every nuguard pentest flag other than --acknowledge-authorization (always explicit, per-invocation, never yaml-configurable) can be set once under a pentest: block in nuguard.yaml, so CI and local runs share one source of truth:

pentest:
  profile: standard
  allow_active_fuzzing: true
  use_sbom_endpoints: true
  scan_timeout: 3600
  fail_on: high
  format: sarif

Precedence: CLI flag > pentest: in nuguard.yaml > built-in default. This block is independent of, and coexists with, the shared target: block used for target/auth resolution.

Reports

Supported formats:

  • text
  • json
  • markdown
  • sarif
nuguard pentest \
  --target https://staging.example.com \
  --acknowledge-authorization \
  --format sarif \
  --output pentest.sarif

Reports are written atomically with owner-only permissions; existing symbolic links are rejected. Nuclei's request, response, curl-command, and template-body fields are dropped. Credential-like values in matched URLs and extracted values are redacted.

Remediation plans

run_pentest builds one deterministic plan after the engine returns normalized findings. Text, JSON, Markdown, and SARIF all consume that same plan. Older, manually constructed reports without a plan still render in their previous shape.

Actions use NuGuard's existing RemediationArtefact model and the explicit RemediationSynthesizer.synthesize_pentest_findings route. Runtime findings produce architectural-change advice, not system-prompt patches or invented source-code locations. No SBOM is required, and this route never calls an LLM.

If the top-level llm: config is set (the same client every other NuGuard command uses, resolved via resolve_remediation_llm_client), the CLI instead calls the async RemediationSynthesizer.synthesize_pentest_findings_async route. It builds the identical deterministic plan first, then replaces each action's implementation guidance with a fix description grounded in that action's own evidence — the matched locations (including query-parameter names like redirect, though values are always blanked), matcher name(s), and finding description(s) — so a developer or coding agent gets an implementable next step instead of generic category text. Everything else on the action (targets, matched locations, rule/CWE/CVE ids, change_detail, verification steps) stays the same deterministic, redacted values — only implementation is LLM-authored. An LLM failure (bad credentials, unreachable model) surfaces as a loud error rather than silently falling back to the generic template. With no llm: config set, behavior is unchanged from the fully deterministic route above.

Guidance precedence: explicit template remediation, then recognized CWE classification, then recognized tags, then a generic review/vendor-fix fallback. Built-in cases cover SQL injection, XSS, SSRF, path traversal, authentication, CSRF, information exposure, TLS, CORS, and exposed deployment or management routes. Multiple recognized weaknesses all contribute guidance rather than one being picked arbitrarily. Classification is scanner-provided evidence, not independent proof a vulnerability exists.

Findings only aggregate when the exact source rule and whitespace-normalized recommended change match. Rule identifiers and remediation text stay case-sensitive. The action ID is derived from those two safe values, not a random UUID, timestamp, or target credentials. Aggregation preserves source finding IDs, targets, matched locations, CVE/CWE IDs, references, tags, and matcher names, and uses the highest source severity. Ordering is deterministic.

The optional runtime context on a shared artefact holds its stable action ID, target and classification metadata, guidance provenance, implementation advice, verification steps, and advisory_only: true. Existing non-runtime artefacts omit this field when serialized. Verification is scoped to each authorized target — absence in a later scan isn't proof of remediation.

The Markdown renderer and remediation-plan exporter are shared with other NuGuard commands. SARIF adds rule help, per-result action IDs, implementation and retest metadata, and a run-level structured plan. It doesn't emit SARIF source edits or fixes, and doesn't duplicate the whole aggregated plan inside every result.

Write an optional separate plan in NuGuard's common remediation JSON format:

nuguard pentest --target https://staging.example.com \
  --acknowledge-authorization --format json --output pentest.json \
  --remediation-output remediation.json

The two output paths must differ. Both use the existing owner-only, atomic report writer with symlink protection — each file is atomic on its own, not as a transaction across both. The plan is written before any severity-threshold exit, and neither the original findings nor the threshold decision changes because of it.

For library-only planning, pass validated Pydantic inputs to the shared route:

from nuguard.remediation.pentest import PentestRemediationFinding
from nuguard.remediation.synthesizer import RemediationSynthesizer

finding = PentestRemediationFinding(
    finding_id="pentest:nuclei:example",
    rule_id="nuclei:example-rule",
    title="Untrusted query input",
    severity="high",
    target="https://staging.example.com/",
    cwe_ids=["CWE-89"],
)
actions = RemediationSynthesizer().synthesize_pentest_findings([finding])
serialized = [action.model_dump(mode="json") for action in actions]

Input prose is bounded and redacted using the existing pentest sanitizers plus conservative HTTP/credential-block rejection. References only permit HTTP(S) and reject user information. Query values and fragments are stripped from plan URLs. Unknown scanner fields and extracted values are deliberately left out — only matcher names are kept. Runtime Markdown treats scanner prose as literal text. No credential configuration or secret file is read for planning.

All actions are advisory. NuGuard never executes commands, applies patches, changes infrastructure/IAM/firewall settings, suppresses findings, or marks anything resolved. Review and apply changes through your normal change process, then retest only within an explicitly authorized scope.

CI thresholds

The default threshold is high. A completed command exits:

  • 0 — no finding reaches the threshold;
  • 1 — a finding reaches the threshold;
  • 2 — authorization, scope, configuration, engine, timeout, or malformed output failure.
nuguard pentest \
  --target https://staging.example.com \
  --acknowledge-authorization \
  --format sarif \
  --output pentest.sarif \
  --fail-on medium

Use --fail-on none if findings shouldn't fail the job.

Authentication

Pentest reuses the shared target.auth configuration and NuGuard's runtime ${ENV_VAR} expansion. It does not inherit redteam.auth, redteam.target, or extra target.headers. Explicit CLI targets never retarget credentials. Authentication resolves only after the authorization acknowledgement. Never commit real credentials or pass credential values as CLI arguments.

target:
  url: https://staging.example.com
  auth:
    type: bearer
    header: "Authorization: Bearer ${APP_TOKEN}"
nuguard pentest --config nuguard.yaml --acknowledge-authorization

Configured modes: bearer, api_key (a custom header), basic, cookie_file, and the opt-in login_flow. They all reuse AuthConfig — there's no separate pentest credential model. Unresolved references fail closed.

For advanced static authentication, provide a native Nuclei Secret File instead:

static:
  - type: query
    domains: [staging.example.com]
    params:
      - key: access_code
        value: REPLACE_PRIVATELY_WITH_A_TEST_CREDENTIAL
chmod 600 /secure/nuclei-secrets.yaml
nuguard pentest --target https://staging.example.com \
  --nuclei-secret-file /secure/nuclei-secrets.yaml \
  --acknowledge-authorization

The native subset supports basicauth, bearertoken, header, cookie (key/value pairs), and query. Unknown fields, duplicate YAML keys, aliases, regex/wildcard domains, unrelated targets, and multiple credentials for one scope are all rejected. Configured auth and a native file can't be combined. Native files hold already-resolved values — NuGuard doesn't expand templates in them.

Authentication is domain-scoped, not path-scoped. Non-default ports must be explicit, e.g. staging.example.com:8443. Because Nuclei collapses ports 80 and 443 to the same credential key, a scan can't authenticate ambiguous HTTP/HTTPS origins on that key. Literal IPv6 auth scopes are currently rejected; use an exact DNS hostname resolving to an approved IPv6 address instead. Don't assume a credential can be limited to one URL path, or that a domain scope alone stops a trusted template from choosing another scheme.

Credential files must be regular, owner-only files with no symbolic links in any path component. Authenticated scans currently require POSIX permission controls. NuGuard validates and copies credentials into its private scan directory as a 0600 Secret File, passes only that path to Nuclei, and removes it when the scan context exits — including on failures and handled interruptions. Abrupt termination (SIGKILL) can't guarantee cleanup.

Netscape cookie files must contain unexpired, host-only cookies for the exact target, with path /. Broad-domain and narrower-path cookies are rejected rather than silently widened. Secure cookies require HTTPS.

--allow-dynamic-auth permits a configured NuGuard login_flow: one POST to the exact authorized origin, using an already-validated IP address while preserving the HTTP Host and TLS verification name. Redirects, proxies, GET logins, cross-origin endpoints, and oversized responses are all rejected. The configured response-key path is used as given, with no automatic discovery. The resulting credential becomes a static Secret File — it's not refreshed mid-scan.

Native dynamic authentication templates stay disabled even with this flag. A trusted-directory check alone doesn't constrain template network requests or make runtime-generated credentials available for safe redaction. There's no --auth-templates-dir option in this implementation.

Authenticated scanner diagnostics are suppressed. Known credential values, URL-encoded forms, and Basic-auth encodings are redacted before findings are normalized, and query values in reported URLs are removed. Raw HTTP records stay excluded. No arbitrary scanner arguments or raw credential flags are accepted. Existing redirect, authorization, and target-scope controls stay active.

Library usage

nuguard.pentest.public_api exposes a typed Pydantic interface for embedding pentest runs in other Python code instead of shelling out to the CLI:

  • PentestRunRequest / PentestAuthConfig / PentestLoginFlowConfig — request models (credentials use SecretStr).
  • run_pentest_async() — run a scan and get back a PentestRunResult.
  • run_pentest_stream() — run a scan and consume live progress as StreamEvents (the same streaming primitives behavior and redteam use), reduced into a PentestProgressState via apply_event_to_pentest_state.

All of the CLI's safety invariants (authorization acknowledgement, target scope validation, signed-templates-only, credential redaction) apply the same way through this interface.