Command Reference#

Global Options#

  • --log-level: Sets the log level. Accepted values are: “trace”, “debug”, “info”, “warn”, “error”, “off”. Default is “warn”.

  • --format: Sets the CLI output format. Accepted values are: “text”, “json”. Default is “text”.

Subcommands#

CoRIM workflow#

Note: The CoRIM verifier is experimental. It is the direction for NVIDIA’s attestation-verification workflow, but its behavior, interfaces, supported evidence, and EAR output may change.

The CoRIM workflow is separate from the legacy TCG RIM workflow. It appraises CMW evidence against CoRIM reference manifests and produces an EAR. The commands below form one flow:

  1. collect-evidence-v2 creates a CMW.

  2. attest-v2 appraises the CMW and produces an EAR.

  3. verify-token with --token-type ear authenticates a signed EAR received by a relying party.

verify-token --token-type ear is the CoRIM relying-party command; there is no separate verify-v2 command.

version#

Displays CLI version information as JSON.

nvattest version
# {
#   "nvattest": "1.0"
# }

collect-evidence#

Collects device evidence from live devices. If global output format is json, the output will be emitted as a JSON document. This evidence can be saved and used with attest --gpu-evidence-source=file or attest --nvswitch-evidence-source=file. [optional]

Options: (see nvattest collect-evidence -h for more information):

  • --device {gpu|nvswitch}: Device to attest. Default is gpu.

  • --nonce: Nonce for the attestation in hex format.

  • --gpu-evidence-source {nvml|corelib|file}: Source of GPU evidence (default: nvml). Used if --device=gpu.

    • nvml: Collects evidence using NVIDIA Management Library (NVML). Requires the NVIDIA GPU driver to be installed and the GPU to be in CC mode.

    • corelib: Collects evidence using the Corelib library. Only to be used outside of CC mode. Requires --gpu-architecture to be specified. Requires root permissions.

    • file: Reads evidence from a previously collected evidence file. Requires --gpu-evidence-file to be specified.

  • --gpu-architecture {blackwell}: GPU architecture. Required if --gpu-evidence-source=corelib.

  • --gpu-evidence-file <path>: Path to a JSON evidence file. Required if --gpu-evidence-source=file.

Example commands:

Collect evidence using NVML:

nvattest collect-evidence --device gpu

Collect evidence using NVML with JSON output:

nvattest collect-evidence --device gpu --format json

Collect evidence using Corelib for Blackwell GPUs:

sudo nvattest collect-evidence --gpu-evidence-source=corelib --gpu-architecture blackwell --format json

Note: You must run with sudo as Corelib requires root privileges to access GPU devices.

Output:#

The output JSON document will contain the following fields:

  • evidences: the attestation evidences as a JSON array (one entry per device)

  • result_code: NVAT SDK return code

  • result_message: NVAT SDK return code string

Example output (truncated):

{
  "evidences": [
    {
      "arch": "HOPPER",
      "nonce": "123..",
      "evidence": "EeAB..",
      "certificate": "LS0t.."
    },
    {
      "evidence": "RfdT..",
      // ...
    }
  ],
  "result_code": 0,
  "result_message": "Ok"
}

collect-evidence-v2#

Creates a CMW collection for the CoRIM verifier.

  • --evidence-source <nvml|corelib|spdm-files>: Select live GPU collection or construct a CMW from an SPDM transcript and PEM certificate chain.

  • --nonce <hex>: Use a supplied challenge. Live collection generates a 32-byte nonce when omitted. For spdm-files, it enables transcript freshness checking during appraisal.

  • --spdm-transcript-file <path> and --cert-chain-file <path>: Required with --evidence-source spdm-files.

Write a live CMW collection to a file:

nvattest collect-evidence-v2 --format json > evidence.cmw.json

The resulting CMW is input to attest-v2.

attest#

Runs attestation for a given device type. If global output format is json, the output will be emitted as a JSON document.

Options: (see nvattest attest -h for more information):

  • --device {gpu|nvswitch}: Device to attest. Default is gpu.

  • --nonce: Nonce for the attestation in hex format.

  • --verifier {local|remote} (default: local)

  • --gpu-evidence-source {nvml|file} (default: nvml)

  • --gpu-evidence-file <path>: JSON evidence file to use when --gpu-evidence-source=file

  • --nvswitch-evidence-source {nscq|file} (default: nscq)

  • --nvswitch-evidence-file <path>: JSON evidence file to use when --nvswitch-evidence-source=file

  • --relying-party-policy <path>: Rego policy file

  • --rim-url: Base URL for the NVIDIA RIM service (e.g.: https://rim.attestation.nvidia.com)

  • --ocsp-url: Base URL for the OCSP responder (e.g.: https://ocsp.ndis.nvidia.com)

  • --ocsp-cert-id-hash {sha-1|sha-256|sha-384}: Digest used to construct OCSP CertID.issuerNameHash and CertID.issuerKeyHash. The default is sha-256. The case-insensitive aliases sha1, sha256, and sha384 are also accepted; SHA-1 is compatibility-only for legacy responders.

  • --nras-url: Base URL for the NVIDIA Remote Attestation Service (e.g.: https://nras.attestation.nvidia.com)

  • --service-key: Service key used to authenticate remote service calls to attestation services. To obtain a service key, follow the NGC Onboarding Guide.

--ocsp-cert-id-hash does not select the OCSP response signature algorithm or any evidence/CoRIM digest. CLI/API selection takes precedence over NVAT_OCSP_CERT_ID_HASH_ALGORITHM; when neither is provided, the environment-aware constructor uses that variable and otherwise defaults to SHA-256.

Behavior:

  • Evidence sources are configured through the {device}-evidence-source options.

    • By default, live evidence is collected through the corresponding device drivers/libraries.

    • File evidence sources can be used to verify evidence that was collected ahead of time for testing or as part of a custom attestation workflow.

    • Note: When an evidence file is provided, the correct nonce corresponding to that evidence must be supplied through the --nonce option.

  • If a Rego policy is supplied, attestation will fail with a specific exit code when the policy does not match.

JSON Output#

The output JSON document will contain the following fields:

  • claims: the attestation claims as a JSON array (one entry per device)

  • detached_eat: the signed detached EAT bundle containing the claim set

  • result_code: NVAT SDK return code

  • result_message: NVAT SDK return code string

Example output (truncated):

{
  "claims": [
    {
      "x-nvidia-device-type": "gpu",
      "secboot": true,
      "x-nvidia-gpu-driver-version": "575.32"
      // ...
    }
  ],
  "detached_eat": [
  	[
  		"JWT",
  		"the-overall-jwt"
  	],
  	{
  		"GPU-0": "jwt-for-this-submodule", 
  		"GPU-1": "jwt-for-this-submodule",
  		// ...
  	}
  ],
  "result_code": 0,
  "result_message": "Ok"
}

See the SDK’s claims schema documentation for the complete schema of the claims.

Example CLI commands#

  • Local GPU attestation:

nvattest attest --device gpu --verifier local

  • Attest using pre‑collected GPU evidence and a custom policy, emitting the results as JSON:

nvattest attest --device gpu \
  --gpu-evidence-source file \
  --gpu-evidence-file ./path/to/gpu_evidence.json \
  --relying-party-policy ./path/to/policy.rego \
  --format json

  • Attest using remote verifier with a service key:

export NV_ATTESTATION_SERVICE_KEY="your-service-key"
nvattest attest --device gpu \
  --verifier remote \
  --nras-url https://nras.attestation.nvidia.com

Note: To obtain a service key, refer to the NGC Onboarding Guide for instructions on setting up your NGC account and generating authentication keys.

  • Rego policy example:

Supply a Rego file that defines package policy and a boolean rule nv_match. If nv_match evaluates to false, the attestation failes with error code `NVAT_RP_POLICY_MISMATCH.

See here for more information

Example rego policy:

package policy
import future.keywords.every
default nv_match := false
nv_match {
  every result in input {
    result["x-nvidia-device-type"] == "gpu"
    result.secboot
    result.dbgstat == "disabled"
  }
}

Pass it with --relying-party-policy option

attest-v2#

Appraises a CMW collection with the local CoRIM verifier and emits EAR JSON.

  • --evidence-source <nvml|file|spdm-files>: Collect live evidence, read a CMW JSON file, or construct CMW input from an SPDM transcript and certificate chain.

  • --evidence-file <path>: Required with --evidence-source file.

  • --verify-rim-signatures / --no-verify-rim-signatures: CoRIM signature verification is enabled by default. Unsigned CoRIMs are for tests only.

  • --verify-revocation / --no-verify-revocation: Certificate revocation checking is enabled by default.

  • --ear-signing-key-file <path>: Private signing key for the EAR JWT. Omitting it produces an unsigned EAR for tests only.

  • --ear-signing-issuer <url> and --ear-signing-kid <id>: Set the JWT issuer and key identifier. For a transported EAR, the issuer must be the HTTPS verifier base URL that serves the corresponding JWKS.

  • --relying-party-policy <path>: Apply Rego to the complete EAR JSON object.

Appraise a previously collected CMW and produce a signed EAR:

nvattest attest-v2 \
  --evidence-source file \
  --evidence-file ./evidence.cmw.json \
  --ear-signing-key-file /etc/nvat/ear-signing-key.pem \
  --ear-signing-issuer https://verifier.example.com \
  --ear-signing-kid ear-signing-key-1 > result.ear.json

The output contains EAR JSON and an ear_jwt member. An EAR with warning or contraindicated status can still be authentic; an explicit relying-party policy decides whether the appraisal is acceptable. See the EAR format reference for the JSON claims.

verify-token#

Verifies a token received from an attesting party without collecting evidence locally. Detached EAT verification remains the default. With --token-type ear, this command is the relying-party step for a signed EAR produced by the CoRIM workflow.

Options: (see nvattest verify-token -h for more information):

  • --token-type <detached-eat|ear>: Token format. The default is detached-eat; select ear for a compact signed EAR JWT.

  • --token-file <path>: Path to the token file. Use -, or omit the option, to read from standard input. EAR input may end with a newline.

  • --nonce <hex>: Optional expected nonce. When supplied, eat_nonce must match it. When omitted, request binding is not checked.

  • --nras-url <url>: NRAS base URL for detached EATs. In EAR mode, this is the trusted verifier base URL selected by the caller; the SDK obtains <nras-url>/.well-known/jwks.json and requires the issuer to match it.

  • --service-key <key>: Optional service key for the JWKS request (also read from NV_ATTESTATION_SERVICE_KEY). It is sent only to HTTPS nvidia.com hosts and subdomains; it is suppressed for other verifier URLs.

  • --clock-skew-leeway-seconds <seconds>: JWT time-claim leeway in EAR mode. The default is 60 seconds; set 0 to require exact clock agreement.

  • --relying-party-policy <path>: Optional Rego policy. It receives decoded claims for detached EATs and the complete authenticated EAR object for EARs.

  • --format <text|json>: Output format. Accepted values are text and json. Default is text. (This is the global --format option; pass it before verify-token or after, either position is accepted.)

EAR mode#

EAR mode verifies the JWT signature, issuer, applicable JWT time claims, and an optional expected nonce. It authenticates the JWT but does not validate EAR schema or appraisal semantics. After successful authentication, a relying-party policy may make the acceptance decision. Without a policy, the command accepts only an EAR whose top-level status and every non-empty submodule status are affirming.

Use EAR mode after attest-v2 has produced a signed token:

jq -r '.ear_jwt' result.ear.json | nvattest verify-token \
  --token-type ear \
  --nras-url https://verifier.example.com \
  --token-file -

Exit codes#

Code

Meaning

0

Token authenticated and accepted by the supplied policy or default decision.

1

Setup, authentication, nonce, policy creation, or policy evaluation failed.

2

Token authenticated, but the supplied policy rejected it.

3

Token authenticated, but the legacy overall result or the default EAR decision rejected it.

Exit 2 occurs only when a supplied policy returns a mismatch. A policy load or evaluation error uses exit 1.

Example commands:

Verify a token against NRAS:

nvattest verify-token \
  --token-file eat.json \
  --nras-url https://nras.attestation.nvidia.com

Verify a token and require it to match the nonce the relying party issued:

nvattest verify-token \
  --token-file eat.json \
  --nras-url https://nras.attestation.nvidia.com \
  --nonce 931d8dd0add203ac3d8b4fbde75e115278eefcdceac5b87671a748f32364dfcb

Verify a token and apply a relying-party policy:

nvattest verify-token \
  --token-file eat.json \
  --nras-url https://nras.attestation.nvidia.com \
  --relying-party-policy ./policy.rego

Output#

JSON output includes result_code and result_message. Detached-EAT mode uses claims; EAR mode uses ear, the complete authenticated EAR object.