fix(onboard): bake corporate CA into DCode cold builds

[cv]

Summary

Before this change, a first Deep Agents Code build could fail behind corporate TLS inspection because its base-image stages did not receive the configured corporate CA.
NemoClaw now validates and installs that CA before the affected HTTPS fetches and installs it again in the final sandbox image.
A locally built base image is reused only when its recorded build inputs match the current corporate CA configuration.

Related Issue

Fixes #8119

Changes

• Add sorted Docker build arguments to the shared Docker adapter for the Deep Agents Code base-image builder, with command construction covered by src/lib/adapters/docker/index.test.ts.
• Pass the existing corporate CA configuration to Deep Agents Code local base-image builds without adding a new user setting.
• Validate that every decoded certificate has basicConstraints CA:TRUE before adding it to build or runtime trust.
• Install the corporate CA before the Deep Agents Code native-package, Debian snapshot, and MCP discovery dependency fetches that require it.
• Decode the corporate CA again in the final sandbox image so published and cached base images receive the current sandbox-specific trust bundle.
• Store corporate CA files with root ownership and mode 0444, and keep their directories at mode 0755.
• Include a hash of build arguments in base-image resolution and provenance keys without recording the argument values in those keys.
• Rebuild or reject a local fallback when its recorded build inputs do not match the current corporate CA configuration.
• Run extracted Dockerfile certificate checks without root privileges while retaining the production ownership commands in source-shape tests.
• Add the corporate CA guide to the Deep Agents Code documentation navigation and describe cold-build behavior.
• Keep dependency manifests, lockfiles, registry locations, and audit thresholds unchanged from current main.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Independent nine-category security review passed at commit 89d1cdafb1a6440c507931b4fde03798a01df148 with no findings.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: None requested; every required check must pass.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: Independently reviewed commit 89d1cdafb1a6440c507931b4fde03798a01df148 against 1ee723a3c0fd61fa6c8217b81035208ef5a68e09. docs/security/configure-corporate-ca-trust.mdx and docs/index.yml publish the Deep Agents Code corporate CA procedure. The documented cold-build and final-image trust behavior matches the Dockerfiles, host-side validation, provenance checks, and regression coverage. The terminology, variant markup, structure, and commands follow the repository writing and documentation guides. GitHub CI provides documentation validation for this commit.
• Agent: Codex Desktop independent documentation writer

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable
• Station profile/scenario: Not applicable
• Result: Not applicable; this PR does not change scripts/prepare-dgx-station-host.sh.
• Supporting evidence: Not applicable

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub — verification is pending after local commit 89d1cdafb1a6440c507931b4fde03798a01df148 is pushed.
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable — commit hooks passed; pre-push is pending.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — GitHub CI is authoritative and pending.
• Applicable broad gate passed — GitHub CI is authoritative and pending.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, credentials, or private keys are added by this diff.
• npm run docs builds without warnings (doc changes only) — GitHub documentation checks are pending.
• Doc pages follow the style guide (doc changes only) — independent documentation review passed.
• New doc pages include SPDX header and frontmatter (new pages only) — Not applicable; this PR adds no page.

GitHub CI is authoritative.
No duplicate local test, documentation, build, or typecheck suite ran after the merge refresh.

Security Review

• Result: PASS
• Reviewed commit: 89d1cdafb1a6440c507931b4fde03798a01df148
• Base commit: 1ee723a3c0fd61fa6c8217b81035208ef5a68e09
• Categories: Secrets and credentials PASS; input validation and data sanitization PASS; authentication and authorization PASS; dependencies and third-party libraries PASS; error handling and logging PASS; cryptography and data protection PASS; configuration and security controls PASS; security testing PASS; system security PASS.
• Evidence: Independent full-diff review found no security findings. The public corporate CA is passed as a separate Docker argument without shell interpolation or content logging. All added parsers require basicConstraints CA:TRUE. File ownership and modes remain explicit. SHA-256 build-argument fingerprints bind local image reuse to the selected CA without recording its value. Incompatible local bases rebuild or fail closed. Negative coverage includes invalid base64, malformed PEM, corrupt bundles, certificate requests, and non-CA leaf certificates. GitHub CI provides execution validation for this commit.
• Agent: Codex Desktop independent security reviewer

---

Signed-off-by: Carlos Villela cvillela@nvidia.com
Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• New Features

  • Added corporate certificate authority support for Deep Agents builds and runtime images.
  • Corporate certificates are validated, securely installed, and available for HTTPS connections during builds and runtime.
  • Docker image builds now support configurable build arguments with consistent handling.
  • Build configuration changes are tracked to select the correct sandbox image.

• Documentation

  • Added guidance for configuring corporate CA trust, including uncached builds and supported Deep Agents variants.

• Bug Fixes

  • Improved reliability for environments using corporate proxies or private certificate authorities.
  • Added clear validation failures for missing or invalid certificate data.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Deep Agents Docker builds now accept a corporate CA bundle, validate and install it in base and final images, and include build arguments in cache resolution. Tests and documentation cover the new flow.

Changes

Corporate CA trust

Layer / File(s)	Summary
Build-argument propagation and cache isolation src/lib/adapters/docker/image.ts, src/lib/adapters/docker/index.test.ts, src/lib/agent/base-image.ts, src/lib/agent/base-image.test.ts, src/lib/sandbox-base-image.ts, src/lib/sandbox-base-image/types.ts, src/lib/sandbox-base-image/resolution-key.ts, src/lib/sandbox-base-image/resolution-key.test.ts	Docker builds accept sorted buildArgs. Deep Agents resolves the corporate CA from the environment and passes it to local builds. Resolution keys and provenance include a deterministic build-argument hash.
Dockerfile CA decoding and trust installation agents/langchain-deepagents-code/Dockerfile.base, agents/langchain-deepagents-code/Dockerfile	The base and final image stages decode and validate NEMOCLAW_CORPORATE_CA_B64, install certificates into system trust, and fail for missing decoding support or invalid certificate data.
Corporate CA build validation test/corporate-ca-build-tls-anchor.test.ts, test/corporate-ca-dockerfile-decode.test.ts, ci/source-shape-test-budget.json	Tests validate CA installation order, final-image decoding, Dockerfile coverage, encoded build arguments, and source-shape exceptions.
Corporate CA documentation docs/security/configure-corporate-ca-trust.mdx, docs/index.yml	The security documentation supports Deep Agents and describes CA handling during base-image and final-image builds.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Suggested labels: area: onboarding, area: security, bug-fix, integration: dcode, platform: container

Sequence Diagram(s)

sequenceDiagram
  participant HostEnvironment
  participant BaseImageResolution
  participant DockerBuild
  participant DeepAgentsBaseImage
  participant DeepAgentsFinalImage
  participant SystemTrustStore

  HostEnvironment->>BaseImageResolution: Provide corporate CA bundle
  BaseImageResolution->>DockerBuild: Pass NEMOCLAW_CORPORATE_CA_B64
  DockerBuild->>DeepAgentsBaseImage: Build base image
  DeepAgentsBaseImage->>SystemTrustStore: Decode, validate, and install CA
  DockerBuild->>DeepAgentsFinalImage: Build final image
  DeepAgentsFinalImage->>SystemTrustStore: Decode, validate, and install CA

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address [#8119] by passing corporate CA data, establishing trust before HTTPS fetches, and testing DCode cold-build paths.
Out of Scope Changes check	✅ Passed	The Docker, resolution-key, documentation, and test changes directly support corporate CA handling for DCode cold builds.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the corporate CA fix for Deep Agents Code cold builds, which is the main change in the pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/8119-ca-bake-cold-build

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 89d1cda in the fix/8119-ca-bake-col... branch remains at 96%, unchanged from commit 5f87afa in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 89d1cda in the fix/8119-ca-bake-col... branch remains at 81%, unchanged from commit 1ee723a in the main branch.

Show a code coverage summary of the most impacted files.

File	main 1ee723a	fix/8119-ca-bake-col... 89d1cda	+/-
src/lib/sandbox...solution-key.ts	100%	97%	-3%
src/lib/agent/base-image.ts	88%	87%	-1%
src/lib/shields/index.ts	69%	69%	0%
src/lib/agent/d...e-base-image.ts	86%	86%	0%
src/lib/onboard...ure-contract.ts	87%	87%	0%
src/lib/sandbox...ion-metadata.ts	98%	98%	0%
src/lib/adapter...docker/image.ts	80%	83%	+3%
src/lib/sandbox-base-image.ts	90%	95%	+5%
src/lib/onboard...shboard-port.ts	90%	96%	+6%
src/lib/onboard...corporate-ca.ts	92%	100%	+8%

---

_{Updated August 04, 2026 03:00 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-8150.docs.buildwithfern.com/nemoclaw

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized terminology decisions differ; normalized E2E selections differ; severity counts match.

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

2 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — cold build at docs/security/configure-corporate-ca-trust.mdx:49: Keep `cold build`; existing documentation already defines it against warm rebuilds.
• established — corporate proxy CA at test/corporate-ca-build-tls-anchor.test.ts:42: Keep `corporate proxy CA`; repository documentation and runtime messages use the same term and meaning.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard, full-e2e, hermes-e2e, ubuntu-repo-cloud-langchain-deepagents-code

1 optional E2E recommendation

• e2e-all

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

agents/langchain-deepagents-code/Dockerfile (1)

32-44: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Pin /usr/local/share/nemoclaw directory permissions explicitly.

mkdir -p /usr/local/share/nemoclaw at line 34 relies on the active umask for the directory mode. Dockerfile.base uses install -d -m 0755 -o root -g root for the same purpose at line 85. Use the same explicit form here for consistent, deterministic permissions on a directory that holds trust material.

🔒️ Proposed fix for explicit directory permissions

-      mkdir -p /usr/local/share/nemoclaw \
+      install -d -o root -g root -m 0755 /usr/local/share/nemoclaw \

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@agents/langchain-deepagents-code/Dockerfile` around lines 32 - 44, Update the
directory creation in the corporate CA setup block to use an explicit root-owned
0755 directory creation, matching the established Dockerfile.base convention,
instead of relying on the active umask. Keep the existing CA decoding,
validation, ownership, and file-permission steps unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/security/configure-corporate-ca-trust.mdx`:
- Line 11: Update the documentation around the agent-variant configuration to
ensure the troubleshooting link is only rendered for supported variants,
`openclaw` and `hermes`; either wrap it in an `openclaw,hermes` block or provide
a corresponding Deep Agents troubleshooting section with a valid anchor.

In `@src/lib/agent/base-image.test.ts`:
- Around line 375-402: Update the test around ensureAgentBaseImage so it forces
the local base-image rebuild path instead of allowing the compatible resolved
image to be reused. Then assert the observable dockerBuild boundary via
dockerBuildMock, verifying its fourth argument contains
NEMOCLAW_CORPORATE_CA_B64 with the resolved certificate value, while retaining
the existing certificate encoding validation as appropriate.

---

Nitpick comments:
In `@agents/langchain-deepagents-code/Dockerfile`:
- Around line 32-44: Update the directory creation in the corporate CA setup
block to use an explicit root-owned 0755 directory creation, matching the
established Dockerfile.base convention, instead of relying on the active umask.
Keep the existing CA decoding, validation, ownership, and file-permission steps
unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 82943362-a46e-4374-bd67-fbcc1f173e41

📥 Commits

Reviewing files that changed from the base of the PR and between c63e7eb and 9653a5d.

📒 Files selected for processing (15)

• agents/langchain-deepagents-code/Dockerfile
• agents/langchain-deepagents-code/Dockerfile.base
• ci/source-shape-test-budget.json
• docs/index.yml
• docs/security/configure-corporate-ca-trust.mdx
• src/lib/adapters/docker/image.ts
• src/lib/adapters/docker/index.test.ts
• src/lib/agent/base-image.test.ts
• src/lib/agent/base-image.ts
• src/lib/sandbox-base-image.ts
• src/lib/sandbox-base-image/resolution-key.test.ts
• src/lib/sandbox-base-image/resolution-key.ts
• src/lib/sandbox-base-image/types.ts
• test/corporate-ca-build-tls-anchor.test.ts
• test/corporate-ca-dockerfile-decode.test.ts

[apurvvkumaria]

Security review for the current revision: PASS with no blocking findings.

Category	Verdict	Evidence
Secrets and credentials	PASS	The CA bundle is a public certificate; no credential paths or secret values are added.
Input validation and sanitization	PASS	Base64 and every X.509 block are validated before trust installation; malformed input fails closed.
Authentication and authorization	PASS	No authentication or authorization behavior changes.
Dependencies and third-party libraries	PASS	No dependency versions or registries change.
Error handling and logging	PASS	Failures are explicit and do not print CA contents or host paths.
Cryptography and data protection	PASS	Node X.509 parsing validates certificate structure; SHA-256 fingerprints bind build arguments without exposing values.
Configuration and secure defaults	PASS	Trust files remain root-owned and read-only; empty CA input is a no-op.
Security testing	PASS	Negative-path decode coverage and ordering checks cover native-security, Perl, Debian snapshot, discovery npm, and final-image trust paths.
Holistic posture	PASS	Builder stages now receive trust before HTTPS operations, closing the cold-build gap without weakening image provenance or sandbox boundaries.

Focused validation passed: plugin build, 56 targeted tests, configured hooks, Dockerfile lint, source-shape budget, test-title policy, and CLI typecheck. The independent documentation writer re-review reports docs-updated with no further changes required.

[apurvvkumaria]

Security review refresh for commit 98dbc12: PASS.

The only change since the full nine-category review is an unset-safe default in two corporate-CA conditionals. It preserves fail-closed validation when a CA is supplied and makes an omitted build argument follow the intended no-CA path under strict shell execution.

Input validation, secrets, authentication and authorization, cryptography, dependency security, sensitive-data handling, privilege boundaries, security testing, and system security remain PASS. The previously failing sandbox-base security-package test now passes, the CA ordering test passes, and the Dockerfile hooks including hadolint pass. The documentation writer confirmed that the existing documentation remains accurate.

Prior full review: #8150 (review)

[apurvvkumaria]

Security and correctness review: PASS for revision 98dbc12.

The corporate CA value remains optional and unset-safe in strict shell execution. When provided, the build decodes into a temporary file, validates a single certificate, installs only after validation, refreshes the trust store, and removes the temporary input. Invalid or multi-certificate payloads fail the build without persisting untrusted material. The cold-build ordering remains correct, and the follow-up does not weaken trust boundaries or expose certificate contents.

Focused Dockerfile security-package and CA-ordering tests pass, Dockerfile hooks pass, the DCode certificate cases pass, and the documentation writer confirmed the existing corporate CA guidance already covers the behavior. The current repository-wide dependency audit remains an external merge blocker and is not waived by this approval.

[apurvvkumaria]

Approved after reviewing revision 88c269e90.

The follow-up commit strengthens the DCode corporate-CA build-argument proof by asserting the actual Docker build invocation and correctly scopes the external-channel troubleshooting link to OpenClaw and Hermes. The merge from current main does not change this PR's feature behavior.

The sensitive-path review remains PASS across secrets, input handling, authorization, dependencies, error handling, cryptography, configuration, security testing, and system boundaries: the CA bytes remain encoded only for the build argument, are represented by provenance rather than value, and are not persisted into logs or registry state. Focused tests pass 25/25, CLI type-check passes, and the documentation writer confirmed all three guide variants with a successful docs build.