NuGuard Platform Integration Guide (Public Pydantic APIs)
Purpose
This guide is the single integration reference for NuGuard platform callers that must use stable, public Pydantic contracts instead of internal classes and direct internal module calls.
It covers:
- Public async entrypoints to call
- Request and response models to use
- SBOM generation/serialization/toolbox APIs
- Streaming API contracts
- Report and target verification APIs
- Migration steps from internal imports/calls
Source of truth
Use these files as the canonical public API surface:
nuguard/analysis/public_api.pynuguard/behavior/public_api.pynuguard/redteam/public_api.pynuguard/policy/public_api.pynuguard/sbom/public_api.pynuguard/sbom/toolbox/public_api.pynuguard/output/public_api.pynuguard/common/target_verify_public_api.pynuguard/common/streaming_models.pynuguard/common/stream_runtime.py
Schema lock for platform-facing models:
tests/contracts/public_api.schema.jsontests/contracts/test_public_api_schema_contract.py
Public API module map
Collapsed chat widgets
Pass browser_discovery on target verification/session and redteam requests, or
config.browser_discovery on behavior requests. The JSON-safe configuration
supports chat_opener_selector, chat_input_selector, send_button_selector, and
chat_ui_timeout_ms (default 10000, range 1-60000). YAML uses shared
target.browser_discovery; behavior/redteam fields override shared fields.
Automatic discovery tries recognizable chat openers only when no eligible input
is visible. A visible loading input is not mistaken for a collapsed widget.
Requests must contain the probe message and must pass HTTP reply validation before
being confirmed or cached. UI failure details appear in warnings/discovery notes,
without raw Playwright exception text. Cancellation is not converted to failure.
verify_target returns endpoint_not_found when endpoint discovery fails; platform
handlers should map that result rather than treating it as an unexpected HTTP 500.
Iframe and closed-shadow-root traversal are not added by this change.
| Domain | Public module | Entry points |
|---|---|---|
| Static analysis | nuguard.analysis.public_api |
run_analysis |
| Behavior | nuguard.behavior.public_api |
analyze_behavior, analyze_behavior_analysis_stream, run_behavior_scenarios, discover_behavior_profile, analyze_behavior_stream, analyze_behavior_static |
| Redteam (v1) | nuguard.redteam.public_api |
run_redteam, run_redteam_stream |
| Cognitive policy | nuguard.policy.public_api |
parse_cognitive_policy |
| SBOM generation/serialization | nuguard.sbom.public_api |
generate_sbom, parse_sbom_json, render_sbom, export_sbom, enrich_sbom |
| SBOM toolbox | nuguard.sbom.toolbox.public_api |
list_toolbox_plugins, run_toolbox_plugin, run_toolbox_all |
| Report rendering/export | nuguard.output.public_api |
render_redteam_report, render_behavior_report, export_validation_report |
| Target verification/session | nuguard.common.target_verify_public_api |
verify_target, resolve_target_session_public |
| Stream contracts | nuguard.common.streaming_models |
StreamEvent, StreamProgressPayload, StreamDeltaPayload, StreamTerminalPayload, reducers |
Request and response contracts
Analysis
Module: nuguard.analysis.public_api
Request model:
AnalysisRunRequest- Checkov, Opengrep (Semgrep fallback), and Gitleaks accept finite positive
*_timeout(120 seconds per process) and*_total_timeout(300 seconds per scanner) settings. Failed or incomplete scans retain partial findings and exposetool_status[tool].status = "error"; callers should distinguish this from complete coverage. Worker cleanup is bounded; cancelling the async caller leaves scanner threads bounded by their configured deadlines.
- Checkov, Opengrep (Semgrep fallback), and Gitleaks accept finite positive
Opengrep is the preferred source scanner. Keep using enable_semgrep, semgrep_timeout,
semgrep_total_timeout, and tool_status["semgrep"]; these names remain compatible.
enable_pip_audit and enable_gitleaks default to True and skip when the binary or inputs
are missing. pip-audit audits resolved Python dependencies via OSV with pip_audit_timeout
(default 300 seconds) and pip_audit_total_timeout (600 seconds). Gitleaks scans source for
secrets with gitleaks_timeout (120 seconds) and gitleaks_total_timeout (300 seconds);
matched secret values are redacted. All deadlines must be finite and positive.
Response model:
AnalysisRunResult
Entry point:
await run_analysis(request, sbom=..., policy=..., llm_client=...)
AnalysisRunResult.remediation_plan is synthesized from findings against the (required) sbom
argument. It is [] only when there are no findings to synthesize against; llm_client is
optional and only upgrades template-based remediation text with LLM-authored content when
supplied. An actual synthesis failure (e.g. a broken llm_client) propagates out of
run_analysis as a visible exception rather than degrading to an empty plan.
Behavior
Module: nuguard.behavior.public_api
Request models:
BehaviorAnalysisRequestBehaviorRunRequest
Response models:
BehaviorAnalysisResultBehaviorRunResult
Entry points:
await analyze_behavior(request, sbom=..., policy=..., controls=..., llm_client=...)await run_behavior_scenarios(request, sbom=..., policy=..., intent=..., llm_client=...)await discover_behavior_profile(config, sbom=..., policy=..., intent=..., llm_client=...)await analyze_behavior_stream(request, ...)(returnsStreamRunHandle[BehaviorRunResult])await analyze_behavior_analysis_stream(request, ...)(returnsStreamRunHandle[BehaviorAnalysisResult])
The analysis stream invokes the same complete orchestration as analyze_behavior exactly once;
callers do not need to plan scenarios or combine internal results.
BehaviorRunResult.remediation_plan (from run_behavior_scenarios) follows the same contract as
analysis: [] only when there are no findings, otherwise a synthesis failure propagates as a
visible exception.
Resume (BehaviorConfig.resume). Both run_behavior_scenarios and BehaviorRunner.run()
support resuming a previously-aborted run: set resume on the BehaviorConfig passed via
BehaviorRunRequest.config to the path of a checkpoint file. On a mid-run failure with at least
one completed scenario, BehaviorRunner.run() raises
nuguard.common.run_checkpoint.PartialRunError (chained from the original exception) and writes a
checkpoint under config.prompt_cache_dir; pass that path back as resume to skip
already-completed scenarios. Unlike redteam (below), run_behavior_scenarios does not currently
populate PartialRunError.partial_result — platform callers catching this error for behavior runs
should read exc.checkpoint_path / exc.cause rather than expect a ready-made BehaviorRunResult.
A checkpoint is fingerprinted against the sbom/policy it was created with; a mismatched resume
raises CheckpointMismatchError instead of silently combining incompatible results.
Redteam (v1 engine)
RedteamRunRequest.defence_regression_timeout bounds the entire regression
pre-pass, including paraphrase generation (default 180 seconds).
defence_regression_probe_timeout bounds each probe including retries (default
30 seconds). Both must be positive. RedteamRunResult.defence_regression_summary
adds variants_failed and timed_out coverage diagnostics. Failed or expired
probes are inconclusive, and incomplete regression coverage prevents an otherwise
clean run from reporting no_findings. These changes add no filesystem or network
side effects beyond the requested scan; cancellation propagates to active probes.
Module: nuguard.redteam.public_api
Request model:
RedteamRunRequestRedteamAuthConfig, withRedteamLoginFlowConfigfor login-based authentication
Response models:
RedteamRunResultRedteamExecutionResult(stream final result type)- Campaign mode (
RedteamRunRequest.mode="campaign", config inRedteamRunRequest.campaign):CampaignConfig,CoverageSummary,ObjectiveExecutionRecord,ReproductionRecord,ConversationBranchSummary,CapabilityObservation,CampaignPlan,EfficiencySummary— additive optional fields onRedteamRunResult; all frozen in the public schema contract.
Entry points:
await run_redteam(request, sbom=..., policy=..., redteam_llm=..., eval_llm=...)await run_redteam_stream(request, sbom=..., ...)(returnsStreamRunHandle[RedteamExecutionResult])
Note:
- This public API wraps redteam v1 orchestration. v2 is out of scope for this contract.
RedteamRunRequest.auth_configuses secret-safe publicRedteamAuthConfigand also accepts internalAuthConfigand applicationAppAuthConfigvalues for compatibility. Bearer, API-key, basic, login-flow, cookie-file, and no-auth variants remain JSON-safe, but ordinary request dumps redact credentials and are diagnostic rather than replayable transport. Resolve platform secret references before constructing the request; runtime values are revealed only when the public wrapper invokes the internal orchestrator.RedteamRunResult.remediation_planfollows the same error contract as analysis/behavior:[]only when there's no sbom/findings, otherwise a synthesis failure propagates.
Agentic-surface options (additive, all defaulted). RedteamRunRequest also accepts
defence_regressions / defence_regression_paraphrases (single-turn must-refuse pre-pass; 0
paraphrases evaluates only the literal message), asm_max_probe_requests (budget for the
GET/OPTIONS-only surface prober; 0 disables it) with asm_extra_inventory_paths, and
trust_context_confirmation_cells (extra identity-binding cells run after the first confirmed
mismatch). Finding gains optional evasion_differential, decorator_name, callback_evidence,
regression_paraphrase_kind, dual_path_verdict, and state_diff_outcome. The prober promotes
only a redacted AsmSummary onto the SBOM AGENT node; raw probe headers and bodies are not
serialized into results.
Resume (RedteamRunRequest.resume_from). Set resume_from to the path of a checkpoint file
from a previous aborted run; already-completed scenarios are skipped and the final result combines
checkpointed and newly-run scenarios/findings. On a mid-run failure with at least one completed
scenario, run_redteam raises nuguard.common.run_checkpoint.PartialRunError (chained from the
original exception) after writing a checkpoint under prompt_cache_dir (or resume_from's parent
directory when resuming). Unlike a bare exception, this error carries everything needed to persist
and continue the run:
exc.checkpoint_path— pass back asresume_fromon the next call.exc.partial_result— a fully-formedRedteamRunResult(JSON-safe,scan_outcomereflecting the abort reason) built from progress made so far, ready to persist/report as-is.exc.cause/exc.partial_payload— the original exception and raw checkpoint payload, for diagnostics.
A checkpoint is fingerprinted against the sbom/policy it was created with; resuming against
different inputs raises CheckpointMismatchError (also from nuguard.common.run_checkpoint)
rather than silently combining incompatible results. Both errors should be imported from
nuguard.common.run_checkpoint, not from nuguard.redteam.public_api.
Campaign checkpoints also bind to the current authentication headers using a
deterministic PBKDF2-HMAC-SHA-256 fingerprint (600,000 iterations, 256-bit output).
Header order and capitalization do not change the fingerprint; credential changes do.
The public salt identifies this fingerprint's purpose and stays fixed for resume across
processes. The fingerprint is an identity label, not a stored password verifier.
Authenticated campaign checkpoints containing the former truncated SHA-256 fingerprint
raise CheckpointMismatchError on resume; start a new campaign after upgrading.
Public request and result schemas are unchanged, and checkpoints contain no raw auth headers.
Cognitive policy parsing
Module: nuguard.policy.public_api
- Request:
CognitivePolicyParseRequest - Result:
CognitivePolicyParseResult, withCognitivePolicyParseDetaildiagnostics - Entry point:
parse_cognitive_policy(request)
Successful parse results can be passed directly as policy= to behavior and red-team entry
points. Failures contain stable sanitized details rather than source Markdown or raw validation
exceptions.
SBOM generation/serialization contracts
Module: nuguard.sbom.public_api
Request models:
SbomGenerateRequestSbomParseRequestSbomRenderRequestSbomExportRequestSbomEnrichmentRequest, withSbomEnrichmentLlmConfigandSbomProbeAuthConfig
Response models:
SbomGenerateResultSbomParseResultSbomRenderResultSbomExportResultSbomEnrichmentResult
Entry points:
await generate_sbom(request)await parse_sbom_json(request)await render_sbom(request, sbom=...)await export_sbom(request, sbom=...)await enrich_sbom(request)
Enrichment validates input and output, operates copy-on-write, and writes only when
output_path is explicitly supplied. The deterministic cache_fingerprint supports
platform-managed caching and excludes API keys and authorization values. Set the opaque
cache_version to invalidate cached work when secret-dependent or external state changes.
Computed and externally cached values use the same SbomEnrichmentResult schema.
Container and deployment layer (AIBOM schema 1.7.0, additive). SbomGenerateRequest.config
(AiSbomConfig) gains scan_images (default false; runs syft on pulled base images and needs
syft plus registry access), max_image_packages (default 200) and image_scan_timeout
(default 120 s). The returned AiSbomDocument gains nested, optional WorkloadDetail,
PortDetail, ScalingDetail, ResourceDetail and ImagePackage models on NodeMetadata
(workload, cloud_provider, os_name/os_version/os_family/os_evidence, image_role,
image_packages, exposed_ports, hosted_by, network_exposure, ...) and six RelationshipType
values (RUNS, BUILT_FROM, HOSTS, EXPOSES, ROUTES_TO, DEPENDS_ON). Consumers that switch
exhaustively on RelationshipType must handle the new values. Environment variables and secrets are
recorded by name only; values are never serialized. See sbom-schema.md for field semantics.
Supported render/export formats:
jsoncyclonedxcyclonedx-extmarkdown
SBOM toolbox contracts
Module: nuguard.sbom.toolbox.public_api
Request models:
ToolboxListPluginsRequestToolboxRunPluginRequestToolboxRunAllRequest
Response models:
ToolboxListPluginsResultToolboxRunPluginResultToolboxRunAllResult
Entry points:
await list_toolbox_plugins(request)await run_toolbox_plugin(request, sbom=...)await run_toolbox_all(request, sbom=...)
Report/export contracts
Module: nuguard.output.public_api
Models:
ValidationReportMetaModelRedteamReportRenderRequest,RedteamReportRenderResultBehaviorReportRenderRequest,BehaviorReportRenderResultValidationReportExportRequest,ValidationReportExportResult
Entry points:
await render_redteam_report(request, run_result=...)await render_behavior_report(request, run_result=...)await export_validation_report(request, redteam_run_result=..., behavior_run_result=...)
Target verify/session contracts
HTTP chat discovery accepts actual reply text, including outputs-only replies
and configured nested response paths. A successful response alone does not
establish an unknown request field: blind discovery uses an omitted-field
validation control naming that specific field, while declared or browser-observed
fields retain their
provenance. Ambiguous greetings cannot create an endpoint confirmation.
If no usable contract can be resolved, Target Verify reports
all_ok=false with an endpoint_not_found check; API-only callers can supply
chat_payload_key and chat_response_key explicitly. This is contract and
connectivity validation, not a guarantee of semantic message processing.
Legacy endpoint confirmations are revalidated under the new rules. Transport exceptions in preflight retain the existing fail-open scan behavior, but do not write a validated endpoint cache entry. Public request/result schemas are unchanged.
Module: nuguard.common.target_verify_public_api
Models:
TargetVerifyRequest,TargetVerifyCheck,TargetVerifyResultTargetSessionResolveRequest,TargetSessionResolveResult- Literal types:
TargetVerifyStatus,EndpointSource
Entry points:
await verify_target(request, sbom=...)await resolve_target_session_public(request, sbom=...)
When an SBOM is supplied, resolve_target_session_public() resolves a static-hosting target URL to the SBOM deployment URL before endpoint probing and session bootstrap. Platform callers should pass their configured target URL and consume effective_target_url from the result rather than duplicate this resolution logic.
WebSocket chat endpoints are handled transparently: when SBOM or live discovery identifies the
chat route as a WebSocket, verify_target (and the redteam/behavior request path) switches to a
persistent WebSocket connection internally instead of per-request HTTP POSTs. There is no field on
TargetVerifyRequest to force this — it is auto-discovery only, selected via an internal sentinel
value on the resolved payload key, not something platform callers set directly.
Streaming contracts
Use shared event contracts from nuguard.common.streaming_models:
StreamEventStreamProgressPayloadStreamDeltaPayloadStreamTerminalPayloadBehaviorProgressState,RedteamProgressState- Reducers:
apply_event_to_behavior_state,apply_event_to_redteam_state
Handle contract from nuguard.common.stream_runtime:
StreamRunHandle[T]with stream iterator, final result retrieval, non-blockingcancel(), andawait wait_closed(timeout=...).
Redteam and behavior streams emit typed events while scenarios execute:
run_startedidentifies the accepted run.scenario_plan_readyestablishes the initial scenario total and can revise it upward when redteam adds an escalation pass.scenario_startedidentifies the scenario being executed.scenario_progressidentifies the completed scenario and reports monotonic completion counts.findings_deltaemits redteam findings and behavior turn reports as scenarios complete.heartbeatmay be emitted during idle long-running phases.completedorfailedis emitted once as the terminal event.
StreamProgressPayload includes scenario_id, scenario_title, scenario_status, current_scenario_type, and progress counts. With concurrent execution, event order reflects runtime completion order rather than planned scenario order. Apply every event with the matching shared reducer; the final result remains authoritative if scan-level aggregation refines findings.
Call handle.cancel() to request cancellation. A cancelled stream emits failed with stable
sanitized metadata and final_result() raises an asyncio.CancelledError subclass. Generic
worker failures raise StreamExecutionError and expose no raw exception message, target response,
or credentials. Use await handle.wait_closed(timeout=...) to bound only the caller's wait; a
timeout does not cancel the underlying scan. Heartbeats and progress updates may be dropped under
queue pressure, while lifecycle and terminal events are retained.
Migration map: internal calls to public contracts
| Existing internal usage pattern | Replace with public contract |
|---|---|
Constructing StaticAnalyzer directly and calling .analyze() |
Build AnalysisRunRequest and call run_analysis |
Constructing BehaviorAnalyzer directly and calling .analyze() |
Build BehaviorAnalysisRequest and call analyze_behavior |
Constructing BehaviorRunner directly for external integration orchestration |
Build BehaviorRunRequest and call run_behavior_scenarios |
| Calling redteam orchestrator internals from platform code | Build RedteamRunRequest and call run_redteam |
Calling SbomGenerator or extractor internals directly from platform code |
Build SbomGenerateRequest and call generate_sbom |
Calling maybe_auto_enrich_sbom or private credential resolvers |
Build SbomEnrichmentRequest and call enrich_sbom |
Calling parse_policy from an implementation module |
Build CognitivePolicyParseRequest and call parse_cognitive_policy |
| Parsing/rendering SBOMs with direct serializer internals | Use parse_sbom_json, render_sbom, and export_sbom |
| Running toolbox plugins through CLI wrappers | Use list_toolbox_plugins, run_toolbox_plugin, or run_toolbox_all |
| Building custom report payloads via internal report modules | Use render_redteam_report, render_behavior_report, or export_validation_report |
| Calling endpoint probe/session resolver internals directly | Use verify_target and resolve_target_session_public |
| Custom ad hoc stream envelopes | Use StreamEvent and the shared payload models/reducers |
Platform migration steps
- Inventory current platform imports
- Find and replace imports from internal runner/orchestrator/report modules in platform code.
- Introduce request-builder adapters
- Convert platform input DTOs into:
AnalysisRunRequestBehaviorAnalysisRequestorBehaviorRunRequestRedteamRunRequestSbomGenerateRequest,SbomRenderRequest,SbomExportRequestToolboxRunPluginRequest/ToolboxRunAllRequest
- report and target verify request models
- Replace execution calls
- Move platform execution to public async entrypoints only.
- Keep
sbom,policy, and LLM clients as explicit keyword args where required by each API.
- Replace report generation glue
- Stop constructing report JSON/Markdown from internal modules.
- Use
nuguard.output.public_apiwrappers.
- Adopt stream handle contract
- For progressive UI updates, call stream APIs and consume
StreamEvent. - Use shared reducers to build platform-side progress state.
- Add schema drift gate in platform CI
- Vendor or fetch
tests/contracts/public_api.schema.jsonand compare against expected integration assumptions. - Track NuGuard upgrades with schema diff review.
Minimal usage examples
Redteam run
from nuguard.redteam.public_api import RedteamRunRequest, run_redteam
request = RedteamRunRequest(
target_url="https://example-app/api",
profile="ci",
chat_path="/chat",
)
result = await run_redteam(
request,
sbom=sbom_doc,
policy=policy_doc,
redteam_llm=redteam_llm_client,
eval_llm=eval_llm_client,
)
Resume an aborted redteam run
from nuguard.common.run_checkpoint import PartialRunError
from nuguard.redteam.public_api import RedteamRunRequest, run_redteam
request = RedteamRunRequest(target_url="https://example-app/api", profile="ci", chat_path="/chat")
try:
result = await run_redteam(request, sbom=sbom_doc, policy=policy_doc)
except PartialRunError as exc:
# exc.partial_result is a ready-to-persist RedteamRunResult; exc.checkpoint_path
# is what to pass back as resume_from on the next attempt.
persist_partial_report(exc.partial_result)
retry_request = request.model_copy(update={"resume_from": str(exc.checkpoint_path)})
result = await run_redteam(retry_request, sbom=sbom_doc, policy=policy_doc)
Behavior analysis
from nuguard.behavior.public_api import BehaviorAnalysisRequest, analyze_behavior
request = BehaviorAnalysisRequest(config=behavior_config, mode="static+dynamic")
result = await analyze_behavior(
request,
sbom=sbom_doc,
policy=policy_doc,
controls=policy_controls,
llm_client=behavior_llm_client,
)
Render redteam report
from nuguard.output.public_api import RedteamReportRenderRequest, render_redteam_report
request = RedteamReportRenderRequest(
run_id="platform-run-123",
include_markdown=True,
include_json_summary=True,
)
rendered = await render_redteam_report(request, run_result=redteam_result)
Verify target
from nuguard.common.auth import LoginFlowConfig
from nuguard.common.target_verify_public_api import TargetVerifyRequest, verify_target
request = TargetVerifyRequest(
target_url="https://example-app",
chat_path="/chat",
auth_type="login_flow",
login_flow=LoginFlowConfig(
endpoint="/api/auth/login",
payload={"username": "${APP_USERNAME}", "password": "${APP_PASSWORD}"},
token_response_key="access_token",
),
)
verify_result = await verify_target(request, sbom=sbom_doc)
Generate and export SBOM
from nuguard.sbom.public_api import SbomExportRequest, SbomGenerateRequest, export_sbom, generate_sbom
generated = await generate_sbom(
SbomGenerateRequest(source_path="./app")
)
exported = await export_sbom(
SbomExportRequest(format="cyclonedx", output_path="./reports/app.cdx.json"),
sbom=generated.sbom,
)
Run toolbox plugin
from nuguard.sbom.toolbox.public_api import ToolboxRunPluginRequest, run_toolbox_plugin
result = await run_toolbox_plugin(
ToolboxRunPluginRequest(plugin_name="dependency_analyze"),
sbom=generated.sbom,
)
Contract governance
When public Pydantic models change intentionally:
- Regenerate
tests/contracts/public_api.schema.json - Ensure
tests/contracts/test_public_api_schema_contract.pypasses - Review schema diff as a platform-impacting change
Reference command:
uv run pytest tests/contracts/test_public_api_schema_contract.py -q
Current known gaps to account for in platform code
- There is no single generated external docs site page yet that auto-docs all request/response fields.
- The schema snapshot is the stable machine-readable source for exact field shapes.
- Redteam and behavior report identity fields are currently not fully harmonized for cross-artifact correlation; platform should rely on explicit run context until identifier harmonization lands.
PartialRunError.partial_result(checkpoint/resume flow, see Redteam and Behavior sections above) is populated byrun_redteambut not byrun_behavior_scenarios— behavior callers must reconstruct/report partial state fromexc.checkpoint_pathandexc.causethemselves. Treat this as CLI-only parity today; a library caller doing behavior resume gets less than the redteam path.- There is no
nuguard.yaml/ request-model field to hand-configure WebSocket auth-message or completion-key framing for a non-standard WS chat protocol — it's auto-discovery only (see Target verify/session contracts above).