docs(security): document local credential storage protections by brandonpelfrey · Pull Request #1592 · NVIDIA/NemoClaw

brandonpelfrey · 2026-04-08T01:15:45Z

Summary

Document how NemoClaw stores host-side credentials, including the plaintext storage model, filesystem permission expectations, and operational hardening guidance.
Link the new guidance from the commands and architecture references so users can discover it from onboarding and host-state docs.

Related Issue

Fixes #1444

Changes

add a new Credential Storage security reference page
document the ~/.nemoclaw/credentials.json location, 0700/0600 permissions, and plaintext storage trade-offs
describe environment variable precedence, rotation/removal guidance, and permission repair steps
link the new page from the docs home page, commands reference, and architecture reference
extend credential tests to verify the expected directory and file permission modes

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)

Code Changes

Formatters applied — npx prek run --all-files auto-fixes formatting (or make format for targeted runs).
Tests added or updated for new or changed behavior.
No secrets, API keys, or credentials committed.
Doc pages updated for any user-facing behavior changes (new commands, changed defaults, new features, bug fixes that contradict existing docs).

Doc Changes

Follows the style guide. Try running the update-docs agent skill to draft changes while
complying with the style guide. For example, prompt your agent with "/update-docs catch up the docs for the new changes I made in this PR."
New pages include SPDX license header and frontmatter, if creating a new page.
Cross-references and links verified.

Signed-off-by: Brandon Pelfrey bpelfrey@nvidia.com

Summary by CodeRabbit

Documentation
- Added comprehensive "Credential Storage" security guide covering storage location, file permissions, plaintext format, environment variable precedence, credential management, and security best practices.
- Updated architecture and commands documentation with cross-references to credential storage guidance.

coderabbitai · 2026-04-08T01:15:59Z

📝 Walkthrough

Walkthrough

Documentation for NemoClaw credential storage security is expanded with a new dedicated security page. Cross-references are added to existing architecture and command documentation. A test assertion verifies filesystem permissions (0700 directory, 0600 file) are applied correctly during credential storage.

Changes

Cohort / File(s)	Summary
Documentation Navigation `docs/index.md`	Added "Credential Storage" page to Security section `toctree` navigation.
Architecture & Command References `docs/reference/architecture.md`, `docs/reference/commands.md`	Updated existing documentation entries to cross-reference new "Credential Storage" security page for details on file permissions, plaintext storage, and hardening guidance.
Credential Storage Security Guide `docs/security/credential-storage.md`	New comprehensive documentation covering storage location (`~/.nemoclaw/credentials.json`), filesystem permissions (`0700` directory, `0600` file), plaintext JSON format, credential lookup precedence, operational guidance for inspection/rotation/deletion, and security recommendations (backup/sync exclusion, short-lived keys, environment variable usage).
Credential Test Assertions `test/credentials.test.js`	Enhanced existing credential storage test to verify filesystem permission hardening by asserting saved directory mode is `0o700` and file mode is `0o600`.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Secrets stored, permissions set tight,
0700 and 0600 in the night,
Plain JSON under Unix's guard,
A security guide, well-penned, not hard,
No encryption, but warnings clear—
Keep credentials safe, year after year!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs(security): document local credential storage protections' clearly and specifically describes the main change: adding security documentation about credential storage.
Linked Issues check	✅ Passed	The PR fully implements the recommended fix from issue `#1444`: creates credential-storage.md with location, plaintext warning, security recommendations, credential rotation/deletion guidance, and audit commands as specified.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue `#1444`: documentation additions (credential storage page, navigation links, architecture/command references) and credential permission test assertions.
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 docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/fix-1444-credential-storage-security-docs

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

coderabbitai

Actionable comments posted: 2

🧹 Nitpick comments (4)

docs/security/credential-storage.md (2)
8-8: Use API key casing in metadata.

keywords uses api key security; update to API key security for glossary consistency.

As per coding guidelines, the correct term is “API key” (and “api key” should be flagged).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/security/credential-storage.md` at line 8, Update the metadata entry
named keywords to use the correct casing "API key security" instead of "api key
security" in the keywords array; locate the keywords array (the line containing
keywords: ["nemoclaw credential storage", "credentials.json", "api key
security"]) and replace "api key security" with "API key security" so the
glossary term "API key" is consistently cased.
40-41: Rewrite permission bullets in active voice.

is created / is written are passive; switch to active phrasing (for example, “NemoClaw creates…”).

As per coding guidelines, active voice is required in docs prose.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/security/credential-storage.md` around lines 40 - 41, Rewrite the two
permission bullets to active voice: replace the passive phrases “is created” and
“is written” with explicit subject actions, e.g., “NemoClaw creates ~/.nemoclaw/
with mode 0700” and “NemoClaw writes ~/.nemoclaw/credentials.json with mode
0600”; ensure the subject “NemoClaw” and the file paths (~/.nemoclaw/ and
~/.nemoclaw/credentials.json) remain in the bullets and keep the numeric modes
unchanged.
docs/reference/architecture.md (1)
181-181: Use active voice and keep this row to one sentence.

Please rephrase this cell to active voice (for example, “NemoClaw saves…”) and avoid multiple sentences on one source line.

As per coding guidelines, docs require active voice and one sentence per line in source.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/reference/architecture.md` at line 181, Rephrase the table row for
`~/.nemoclaw/credentials.json` into a single active-voice sentence that starts
with the agent (e.g., "NemoClaw saves...") and keeps the existing meaning and
link to Credential Storage; ensure it is one sentence on a single source line
and mentions that credentials are stored as plaintext JSON protected by local
filesystem permissions (preserve the "[Credential
Storage](../security/credential-storage.md)" reference).
docs/reference/commands.md (1)
76-76: Rephrase to active voice and split into one sentence per line.

Use an active subject (for example, “NemoClaw stores credentials…”) and keep each sentence on its own source line.

As per coding guidelines, docs require active voice and one sentence per line in source.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/reference/commands.md` at line 76, Change the passive sentence into
active voice and put each sentence on its own source line: replace "Credentials
are stored in `~/.nemoclaw/credentials.json`. For file permissions, plaintext
storage behavior, and hardening guidance, see [Credential
Storage](../security/credential-storage.md)." with two lines such as "NemoClaw
stores credentials in `~/.nemoclaw/credentials.json`." and "For file
permissions, plaintext storage behavior, and hardening guidance, see [Credential
Storage](../security/credential-storage.md)." updating
docs/reference/commands.md accordingly.

🤖 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/credential-storage.md`:
- Line 23: Update the top-level H1 to exactly match the frontmatter key
title.page: replace the current H1 "Credential Storage" with "NemoClaw
Credential Storage" so the page heading and title.page value are identical;
verify the H1 line (the single leading "# ..." heading) is changed and no other
headings are altered.
- Around line 128-133: Add a new "Next Steps" section after the existing
"Related Files" section: create a final header "Next Steps" that lists links to
the related docs already referenced (e.g., ./best-practices.md and
../reference/architecture.md) and any other next-reading resources relevant to
credential-storage; ensure the section follows the same link style as the rest
of the file and appears as the final section of the page.

---

Nitpick comments:
In `@docs/reference/architecture.md`:
- Line 181: Rephrase the table row for `~/.nemoclaw/credentials.json` into a
single active-voice sentence that starts with the agent (e.g., "NemoClaw
saves...") and keeps the existing meaning and link to Credential Storage; ensure
it is one sentence on a single source line and mentions that credentials are
stored as plaintext JSON protected by local filesystem permissions (preserve the
"[Credential Storage](../security/credential-storage.md)" reference).

In `@docs/reference/commands.md`:
- Line 76: Change the passive sentence into active voice and put each sentence
on its own source line: replace "Credentials are stored in
`~/.nemoclaw/credentials.json`. For file permissions, plaintext storage
behavior, and hardening guidance, see [Credential
Storage](../security/credential-storage.md)." with two lines such as "NemoClaw
stores credentials in `~/.nemoclaw/credentials.json`." and "For file
permissions, plaintext storage behavior, and hardening guidance, see [Credential
Storage](../security/credential-storage.md)." updating
docs/reference/commands.md accordingly.

In `@docs/security/credential-storage.md`:
- Line 8: Update the metadata entry named keywords to use the correct casing
"API key security" instead of "api key security" in the keywords array; locate
the keywords array (the line containing keywords: ["nemoclaw credential
storage", "credentials.json", "api key security"]) and replace "api key
security" with "API key security" so the glossary term "API key" is consistently
cased.
- Around line 40-41: Rewrite the two permission bullets to active voice: replace
the passive phrases “is created” and “is written” with explicit subject actions,
e.g., “NemoClaw creates ~/.nemoclaw/ with mode 0700” and “NemoClaw writes
~/.nemoclaw/credentials.json with mode 0600”; ensure the subject “NemoClaw” and
the file paths (~/.nemoclaw/ and ~/.nemoclaw/credentials.json) remain in the
bullets and keep the numeric modes 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: Pro

Run ID: a84f4d66-1dc7-4d1f-abf5-0c887f0e3790

📥 Commits

Reviewing files that changed from the base of the PR and between edc561a and 6bfeb23.

📒 Files selected for processing (5)

docs/index.md
docs/reference/architecture.md
docs/reference/commands.md
docs/security/credential-storage.md
test/credentials.test.js

coderabbitai · 2026-04-08T01:20:07Z

+  SPDX-License-Identifier: Apache-2.0
+-->
+
+# Credential Storage


⚠️ Potential issue | 🟡 Minor

Align H1 with frontmatter title.page.

The H1 is Credential Storage, but title.page is NemoClaw Credential Storage. These should match exactly.

As per coding guidelines, new pages must have an H1 heading that 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/credential-storage.md` at line 23, Update the top-level H1 to exactly match the frontmatter key title.page: replace the current H1 "Credential Storage" with "NemoClaw Credential Storage" so the page heading and title.page value are identical; verify the H1 line (the single leading "# ..." heading) is changed and no other headings are altered.

coderabbitai · 2026-04-08T01:20:07Z

+## Related Files
+
+Other NemoClaw host-side state also lives under `~/.nemoclaw/`, such as sandbox registry metadata.
+These files are operational state, not provider secrets, but they should still remain in a user-owned home directory.
+
+For the broader sandbox security model and operational trade-offs, see [Security Best Practices](./best-practices.md) and [Architecture](../reference/architecture.md).


⚠️ Potential issue | 🟡 Minor

Add a Next Steps section at the bottom.

This ends with Related Files; for new pages, the final section should be Next Steps with related doc links.

As per coding guidelines, new docs pages must include a “Next Steps” section at the bottom linking to related pages.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed. In `@docs/security/credential-storage.md` around lines 128 - 133, Add a new "Next Steps" section after the existing "Related Files" section: create a final header "Next Steps" that lists links to the related docs already referenced (e.g., ./best-practices.md and ../reference/architecture.md) and any other next-reading resources relevant to credential-storage; ensure the section follows the same link style as the rest of the file and appears as the final section of the page.

…#1592) ## Summary Document how NemoClaw stores host-side credentials, including the plaintext storage model, filesystem permission expectations, and operational hardening guidance. Link the new guidance from the commands and architecture references so users can discover it from onboarding and host-state docs. ## Related Issue Fixes NVIDIA#1444 ## Changes - add a new `Credential Storage` security reference page - document the `~/.nemoclaw/credentials.json` location, `0700`/`0600` permissions, and plaintext storage trade-offs - describe environment variable precedence, rotation/removal guidance, and permission repair steps - link the new page from the docs home page, commands reference, and architecture reference - extend credential tests to verify the expected directory and file permission modes ## Type of Change - [ ] Code change for a new feature, bug fix, or refactor. - [x] 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. - [x] `make docs` builds without warnings. (for doc-only changes) ## Checklist ### General - [x] I have read and followed the [contributing guide](https://github.com/NVIDIA/NemoClaw/blob/main/CONTRIBUTING.md). - [x] I have read and followed the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md). (for doc-only changes) ### Code Changes - [ ] Formatters applied — `npx prek run --all-files` auto-fixes formatting (or `make format` for targeted runs). - [x] Tests added or updated for new or changed behavior. - [x] No secrets, API keys, or credentials committed. - [x] Doc pages updated for any user-facing behavior changes (new commands, changed defaults, new features, bug fixes that contradict existing docs). ### Doc Changes - [x] Follows the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md). Try running the `update-docs` agent skill to draft changes while complying with the style guide. For example, prompt your agent with "`/update-docs` catch up the docs for the new changes I made in this PR." - [x] New pages include SPDX license header and frontmatter, if creating a new page. - [x] Cross-references and links verified. --- Signed-off-by: Brandon Pelfrey <bpelfrey@nvidia.com>  ## Summary by CodeRabbit * **Documentation** * Added comprehensive "Credential Storage" security guide covering storage location, file permissions, plaintext format, environment variable precedence, credential management, and security best practices. * Updated architecture and commands documentation with cross-references to credential storage guidance.

docs(security): document local credential storage protections

6bfeb23

brandonpelfrey requested a review from miyoungc April 8, 2026 01:15

coderabbitai Bot reviewed Apr 8, 2026

View reviewed changes

miyoungc approved these changes Apr 8, 2026

View reviewed changes

brandonpelfrey merged commit df2b91a into main Apr 8, 2026
14 checks passed

cv deleted the docs/fix-1444-credential-storage-security-docs branch April 8, 2026 03:19

cv mentioned this pull request Apr 9, 2026

docs(security): address documentation gaps for auth, credentials, and policies #1487

Closed

2 tasks

wscurran added the chore Build, CI, dependency, or tooling maintenance label Jun 8, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(security): document local credential storage protections#1592

docs(security): document local credential storage protections#1592
brandonpelfrey merged 1 commit into
mainfrom
docs/fix-1444-credential-storage-security-docs

brandonpelfrey commented Apr 8, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Apr 8, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

coderabbitai Bot Apr 8, 2026

Uh oh!

coderabbitai Bot Apr 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

brandonpelfrey commented Apr 8, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Type of Change

Testing

Checklist

General

Code Changes

Doc Changes

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

brandonpelfrey commented Apr 8, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Apr 8, 2026 •

edited

Loading