docs: add security best practices

[miyoungc]

Summary

Adds a comprehensive "Security Best Practices" page that documents every configurable security control in NemoClaw—defaults, what each knob protects, the concrete risk of relaxing it, and recommendations for common use cases.

Changes

• New page: docs/security/best-practices.md covering all four protection layers (network, filesystem, process, inference) with a Mermaid diagram of the default post-onboard posture.
• Navigation: added a "Security" toctree section and an Explore-grid card in docs/index.md.
• README: added a row linking to the new page in the documentation table.
• Cross-references to upstream OpenShell Security Best Practices for platform-level controls (seccomp, SSRF, TLS termination, etc.).
• Three posture profiles (Locked-Down, Development, Integration Testing) and a "Common Mistakes" table covering the most frequent ways people weaken their sandbox security.

Type of Change

• Code change for a new feature, bug fix, or refactor.
• Code change with doc updates.
• Doc only. Prose changes without code sample modifications.
• Doc only. Includes code sample changes.

Testing

• npx prek run --all-files passes (or equivalently make check).
• npm test passes.
• make docs builds without warnings. (for doc-only changes)

Checklist

General

• I have read and followed the contributing guide.
• I have read and followed the style guide. (for doc-only changes)

Doc Changes

• Follows the style guide.
• New pages include SPDX license header and frontmatter, if creating a new page.
• Cross-references and links verified.

---

Signed-off-by: Miyoung Choi miyoungc@nvidia.com

Summary by CodeRabbit

• Documentation
  • Added a comprehensive "Security Best Practices" page covering deny-by-default controls across network, filesystem, process, and inference layers, posture profiles, provider trust tiers, experimental provider guidance, common security pitfalls, and recommended alternatives.
  • Integrated the new guidance into the main documentation navigation and the Explore grid for easier discovery.
  • Added a "Security Best Practices" entry to the documentation table.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

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

Added a new "Security Best Practices" documentation page, a Security card and hidden toctree entry in the docs index, and a new README documentation table row. All edits are documentation-only.

Changes

Cohort / File(s)	Summary
README Documentation README.md	Inserted a "Security Best Practices" row into the documentation table.
Index Navigation docs/index.md	Added a "Security Best Practices" card to the Explore grid and a hidden Security toctree entry linking security/best-practices for grouping/navigation.
Security Best Practices Page docs/security/best-practices.md	Added a new published page describing NemoClaw's deny-by-default security model across network, filesystem, process, and inference layers; includes enforcement details, operator approval flow, shipped policy presets, posture profiles, diagrams, and related links (+~457 lines).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Poem

🐰 I hopped through docs with careful paws,
I penned the locks and sketched the laws.
Four layers guarded, neat and bright,
Sandbox snug through day and night.
A carrot nod to safety's light. 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: add security best practices' accurately and clearly describes the main change: addition of a comprehensive security best practices documentation page with supporting navigation updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/add-best-practices

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (5)

docs/security/best-practices.md (5)

408-415: Consider renaming to "Next Steps".

The page structure guideline recommends a "Next Steps" section at the bottom linking to related pages. This section is titled "Related Topics", which serves the same purpose but uses different naming.

As per coding guidelines: "A 'Next Steps' section at the bottom links to related pages."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/security/best-practices.md` around lines 408 - 415, Rename the "Related
Topics" section header to "Next Steps" to match the page structure guideline:
update the header string "Related Topics" to "Next Steps" while keeping the
existing list of links (e.g., "[Network Policies]", "[Customize the Network
Policy]", etc.) unchanged; also search for any internal references or anchors
that expect the old header text and update them if necessary so links/TOC remain
correct.

---

224-225: Use active voice.

Both sentences use passive voice: "The following capabilities are dropped" and "The following are kept".

Suggestion: "The entrypoint drops the following capabilities" and "The entrypoint keeps the following capabilities."

As per coding guidelines: "Active voice required. Flag passive constructions."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/security/best-practices.md` around lines 224 - 225, Reword the two
passive sentences to active voice: replace "The following capabilities are
dropped: ..." with "The entrypoint drops the following capabilities: ..." and
replace "The following are kept because the entrypoint needs them for privilege
separation via gosu: ..." with "The entrypoint keeps the following capabilities
because it needs them for privilege separation via gosu: ...". Ensure the
capability lists (`cap_net_raw`, `cap_dac_override`, etc., and `cap_chown`,
`cap_setuid`, etc.) remain unchanged and preserve punctuation.

---

141-141: Use active voice.

The sentence "Approved endpoints are merged into the sandbox's policy" uses passive voice. Rewrite to identify who performs the action.

Suggestion: "OpenShell merges approved endpoints into the sandbox's policy as a new durable revision."

As per coding guidelines: "Active voice required. Flag passive constructions."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/security/best-practices.md` at line 141, Replace the passive sentence
"Approved endpoints are merged into the sandbox's policy as a new durable
revision." with an active-voice construction that names the actor; e.g., change
it to "OpenShell merges approved endpoints into the sandbox's policy as a new
durable revision, which persists across sandbox restarts within the same sandbox
instance." Update the surrounding sentence that mentions sandbox destruction so
it still reads clearly (e.g., keep "However, when the sandbox is destroyed and
recreated... the policy resets to the baseline defined in the blueprint.").

---

192-192: Avoid superlative language.

The phrase "the single most dangerous" is superlative/marketing language. Say what it does and what the risk is, without the emphasis.

Suggestion: "A writable .openclaw directory lets the agent modify its own gateway config: disabling CORS, changing auth tokens, or redirecting inference to an attacker-controlled endpoint. This eliminates the credential isolation layer."

As per coding guidelines: "Superlatives and marketing language... Say what it does, not how great it is." (LLM pattern detected.)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/security/best-practices.md` at line 192, Replace the superlative phrase
"the single most dangerous filesystem change" in the sentence that begins "A
writable `.openclaw` directory lets the agent modify its own gateway config..."
with a factual risk statement (e.g., "This eliminates the credential isolation
layer." or similar) so the sentence describes the concrete impact without
marketing/superlative language; update the sentence text in
docs/security/best-practices.md accordingly.

---

167-167: Use active voice.

The sentence "System directories are mounted read-only" uses passive voice. Consider: "The container runtime mounts system directories read-only" or "NemoClaw mounts system directories read-only."

As per coding guidelines: "Active voice required. Flag passive constructions."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/security/best-practices.md` at line 167, The sentence "System
directories are mounted read-only" uses passive voice; change it to active voice
by specifying the actor—e.g., replace it with "The container runtime mounts
system directories read-only" or "NemoClaw mounts system directories read-only"
so the sentence names the subject performing the action and preserves the
original meaning.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/security/best-practices.md`:
- Line 21: The H1 heading in the document does not match the frontmatter
title.page value; update the H1 heading (the top-level heading line) to exactly
match the frontmatter `title.page` string "NemoClaw Security Best Practices —
Controls, Risks, and Posture Profiles" so the H1 and `title.page` are identical.

---

Nitpick comments:
In `@docs/security/best-practices.md`:
- Around line 408-415: Rename the "Related Topics" section header to "Next
Steps" to match the page structure guideline: update the header string "Related
Topics" to "Next Steps" while keeping the existing list of links (e.g.,
"[Network Policies]", "[Customize the Network Policy]", etc.) unchanged; also
search for any internal references or anchors that expect the old header text
and update them if necessary so links/TOC remain correct.
- Around line 224-225: Reword the two passive sentences to active voice: replace
"The following capabilities are dropped: ..." with "The entrypoint drops the
following capabilities: ..." and replace "The following are kept because the
entrypoint needs them for privilege separation via gosu: ..." with "The
entrypoint keeps the following capabilities because it needs them for privilege
separation via gosu: ...". Ensure the capability lists (`cap_net_raw`,
`cap_dac_override`, etc., and `cap_chown`, `cap_setuid`, etc.) remain unchanged
and preserve punctuation.
- Line 141: Replace the passive sentence "Approved endpoints are merged into the
sandbox's policy as a new durable revision." with an active-voice construction
that names the actor; e.g., change it to "OpenShell merges approved endpoints
into the sandbox's policy as a new durable revision, which persists across
sandbox restarts within the same sandbox instance." Update the surrounding
sentence that mentions sandbox destruction so it still reads clearly (e.g., keep
"However, when the sandbox is destroyed and recreated... the policy resets to
the baseline defined in the blueprint.").
- Line 192: Replace the superlative phrase "the single most dangerous filesystem
change" in the sentence that begins "A writable `.openclaw` directory lets the
agent modify its own gateway config..." with a factual risk statement (e.g.,
"This eliminates the credential isolation layer." or similar) so the sentence
describes the concrete impact without marketing/superlative language; update the
sentence text in docs/security/best-practices.md accordingly.
- Line 167: The sentence "System directories are mounted read-only" uses passive
voice; change it to active voice by specifying the actor—e.g., replace it with
"The container runtime mounts system directories read-only" or "NemoClaw mounts
system directories read-only" so the sentence names the subject performing the
action and preserves the original meaning.

🪄 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: Pro

Run ID: 1c542ee6-4937-41ce-a77d-c4d1062dba45

📥 Commits

Reviewing files that changed from the base of the PR and between 82789a6 and 2d60cd9.

📒 Files selected for processing (3)

• README.md
• docs/index.md
• docs/security/best-practices.md

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

docs/security/best-practices.md (3)

408-416: Use a Next Steps section title at the bottom.

The page ends with Related Topics; this should be a Next Steps section with the same links.

As per coding guidelines: "A 'Next Steps' section at the bottom links to related pages."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/security/best-practices.md` around lines 408 - 416, Change the final
section header text from "Related Topics" to "Next Steps" while keeping the same
list of links unchanged; locate the markdown header "## Related Topics" and
replace it with "## Next Steps" so the page ends with the required Next Steps
section linking to the same pages.

---

149-149: Keep one sentence per source line.

This line contains multiple sentences; split them onto separate lines for diff readability.

As per coding guidelines: "One sentence per line in source (makes diffs readable)."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/security/best-practices.md` at line 149, The markdown row containing "|
What you can change | The system merges approved endpoints into the sandbox's
policy as a new durable revision. They persist across sandbox restarts within
the same sandbox instance. However, when you destroy and recreate the sandbox
(for example, by running `nemoclaw onboard`), the policy resets to the baseline
defined in the blueprint." has multiple sentences on one source line; split this
into separate source lines so each sentence is its own line (e.g., keep the
table cell start and then put each sentence on a new line inside that cell) to
satisfy the "one sentence per line" guideline and make diffs readable.

---

169-169: Replace bold callouts with MyST admonitions (LLM pattern detected).

Using **Recommendation:** as prose emphasis violates the callout style rule; use :::{note} / :::{tip} / :::{warning} instead.

As per coding guidelines: "Use MyST admonitions (:::{tip}, :::{note}, :::{warning}) for callouts, not bold text or blockquotes."

Also applies to: 349-349

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/security/best-practices.md` at line 169, The bold callout
"Recommendation:" should be converted to a MyST admonition; locate the text
containing "**Recommendation:**" (e.g., the sentence starting "Apply presets
only when the agent's task requires the integration...") and replace the bold
prefix and surrounding prose with an appropriate MyST admonition block (e.g.,
:::{tip} or :::{note} / :::{warning} depending on intent) so the content is
wrapped as :::{tip} ... ::: (and closes the block) instead of using bold
emphasis; apply the same change for the other occurrence that the reviewer
flagged (the "**Recommendation:**" instance around line 349) so all callouts use
MyST admonitions rather than bold text.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/security/best-practices.md`:
- Around line 17-18: The SPDX header in the file does not match the repo
template; update the two header lines to the exact required text: replace the
current copyright line with "// SPDX-FileCopyrightText: Copyright (c) 2026
NVIDIA CORPORATION & AFFILIATES. All rights reserved." and ensure the license
line is "// SPDX-License-Identifier: Apache-2.0" (include the leading "// " and
the exact year 2026).

---

Nitpick comments:
In `@docs/security/best-practices.md`:
- Around line 408-416: Change the final section header text from "Related
Topics" to "Next Steps" while keeping the same list of links unchanged; locate
the markdown header "## Related Topics" and replace it with "## Next Steps" so
the page ends with the required Next Steps section linking to the same pages.
- Line 149: The markdown row containing "| What you can change | The system
merges approved endpoints into the sandbox's policy as a new durable revision.
They persist across sandbox restarts within the same sandbox instance. However,
when you destroy and recreate the sandbox (for example, by running `nemoclaw
onboard`), the policy resets to the baseline defined in the blueprint." has
multiple sentences on one source line; split this into separate source lines so
each sentence is its own line (e.g., keep the table cell start and then put each
sentence on a new line inside that cell) to satisfy the "one sentence per line"
guideline and make diffs readable.
- Line 169: The bold callout "Recommendation:" should be converted to a MyST
admonition; locate the text containing "**Recommendation:**" (e.g., the sentence
starting "Apply presets only when the agent's task requires the integration...")
and replace the bold prefix and surrounding prose with an appropriate MyST
admonition block (e.g., :::{tip} or :::{note} / :::{warning} depending on
intent) so the content is wrapped as :::{tip} ... ::: (and closes the block)
instead of using bold emphasis; apply the same change for the other occurrence
that the reviewer flagged (the "**Recommendation:**" instance around line 349)
so all callouts use MyST admonitions rather than bold text.

🪄 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: Pro

Run ID: 96c75c7c-ba8d-48a6-9832-d5f0d6390ac9

📥 Commits

Reviewing files that changed from the base of the PR and between 2d60cd9 and 4fd5ff3.

📒 Files selected for processing (1)

• docs/security/best-practices.md

[miyoungc]

I'll merge when the companion PR is also ready to merge in OpenShell NVIDIA/OpenShell#714

[coderabbitai]

♻️ Duplicate comments (1)

docs/security/best-practices.md (1)

21-21: ⚠️ Potential issue | 🟡 Minor

H1 still does not match title.page.

The H1 should exactly match the frontmatter title.page value to satisfy page-structure requirements.

As per coding guidelines, "H1 heading matches the title.page frontmatter value."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/security/best-practices.md` at line 21, The top-level H1 in the document
does not exactly match the frontmatter key title.page; update the document's
first heading (the H1 line, currently "# Security Best Practices") so it exactly
equals the value of title.page in the frontmatter (matching case, punctuation,
and spacing) to satisfy the "H1 heading matches the `title.page` frontmatter
value" requirement.

🧹 Nitpick comments (2)

docs/security/best-practices.md (2)

441-449: Use a “Next Steps” section at the bottom (with an intro sentence).

The page ends with Related Topics; the docs structure requires a bottom Next Steps section linking related pages, and sections should begin with an introductory sentence.

As per coding guidelines, "A "Next Steps" section at the bottom links to related pages." and "Sections use H2 and H3, each starting with an introductory sentence."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/security/best-practices.md` around lines 441 - 449, The doc ends with an
H2 "Related Topics" but must instead include a bottom "Next Steps" H2 that
begins with an introductory sentence; add a new "Next Steps" section after the
existing content that opens with one concise sentence (e.g., "Next steps for
implementing these practices include the following resources:") and move or
re-link the list currently under "Related Topics" into this section as the
related links; also ensure that the "Related Topics" and any other H2/H3
headings in this file start with a one-sentence intro paragraph immediately
beneath the heading (update "Related Topics" to follow that pattern or remove
duplicate headings so only "Next Steps" remains at the bottom).

---

202-202: Avoid bolded “Recommendation:” labels in prose (LLM pattern detected).

Use a normal sentence or a MyST admonition for callouts instead of bold routine labels.

As per coding guidelines, "Unnecessary bold on routine instructions ... should be flagged." and "Use MyST admonitions (:::{tip}, :::{note}, :::{warning}) for callouts, not bold text or blockquotes."

Also applies to: 382-382

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/security/best-practices.md` at line 202, Replace the bolded label
"**Recommendation:**" used before the sentence "Apply presets only when the
agent's task requires the integration..." with either a plain sentence
("Recommendation: Apply presets only when...") or convert the callout to a MyST
admonition (e.g., :::tip / :::note) so it follows the project's style rules
against bolded routine labels; do the same for the other identical bolded
"**Recommendation:**" instance mentioned in the review (the other occurrence in
the document).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@docs/security/best-practices.md`:
- Line 21: The top-level H1 in the document does not exactly match the
frontmatter key title.page; update the document's first heading (the H1 line,
currently "# Security Best Practices") so it exactly equals the value of
title.page in the frontmatter (matching case, punctuation, and spacing) to
satisfy the "H1 heading matches the `title.page` frontmatter value" requirement.

---

Nitpick comments:
In `@docs/security/best-practices.md`:
- Around line 441-449: The doc ends with an H2 "Related Topics" but must instead
include a bottom "Next Steps" H2 that begins with an introductory sentence; add
a new "Next Steps" section after the existing content that opens with one
concise sentence (e.g., "Next steps for implementing these practices include the
following resources:") and move or re-link the list currently under "Related
Topics" into this section as the related links; also ensure that the "Related
Topics" and any other H2/H3 headings in this file start with a one-sentence
intro paragraph immediately beneath the heading (update "Related Topics" to
follow that pattern or remove duplicate headings so only "Next Steps" remains at
the bottom).
- Line 202: Replace the bolded label "**Recommendation:**" used before the
sentence "Apply presets only when the agent's task requires the integration..."
with either a plain sentence ("Recommendation: Apply presets only when...") or
convert the callout to a MyST admonition (e.g., :::tip / :::note) so it follows
the project's style rules against bolded routine labels; do the same for the
other identical bolded "**Recommendation:**" instance mentioned in the review
(the other occurrence in the document).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4c175a7b-644d-4bd1-beed-b2c50e165e32

📥 Commits

Reviewing files that changed from the base of the PR and between 3cc4791 and ff49721.

📒 Files selected for processing (1)

• docs/security/best-practices.md

[miyoungc]

commented xref to openshell docs out for now. merging.