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-dastand stops excludingfuzz/intrusivetags. 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 fromstorage.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-privateis 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:
- An explicit file:
--openapi-spec ./openapi.json. - The target's own live spec, probed at
/openapi.jsonand similar paths (--live-openapi, on by default;--no-live-openapidisables it). - A document synthesized from
--config's SBOMAPI_ENDPOINTnodes — their discovered method, path, and request-body field types — used when the target serves no live spec. Controlled by--use-sbom-endpoints(alsopentest.use_sbom_endpoints), on by default wheneversbom: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:
textjsonmarkdownsarif
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 useSecretStr).run_pentest_async()— run a scan and get back aPentestRunResult.run_pentest_stream()— run a scan and consume live progress asStreamEvents (the same streaming primitivesbehaviorandredteamuse), reduced into aPentestProgressStateviaapply_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.