UAT: `agents diagnostics` does not check config file permissions — spec requires warning when config.toml is world-readable #1907

New issue

Open

opened 2026-04-03 00:11:37 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 00:11:37 +00:00

Owner

Metadata

Branch: fix/diagnostics-config-file-permissions
Commit Message: fix(diagnostics): check config.toml permissions and warn when world-readable
Milestone: v3.3.0
Parent Epic: #362

Bug Report

Summary

The agents diagnostics command's _check_file_permissions() function checks the data directory (data/) for read/write access, but does NOT check the permissions of the configuration file (~/.cleveragents/config.toml). The specification explicitly requires that diagnostics warn when the config file has overly permissive permissions, since the config file stores sensitive values including server.token in plaintext.

Expected Behavior (from spec)

Per specification section "Secret Management" (line 46052):

The config file should have restrictive permissions (chmod 600). The agents diagnostics command warns if config file permissions are too permissive.

The diagnostics command should:

Check the permissions of ~/.cleveragents/config.toml
Emit a WARN status if the file is readable by group or others (i.e., permissions are not 600 or stricter)

Actual Behavior

The _check_file_permissions() function in src/cleveragents/cli/commands/system.py only checks the data directory:

def _check_file_permissions() -> dict[str, Any]:
    """Check file permissions on the data directory."""
    settings = get_settings()
    data_dir = settings.data_dir
    # Only checks data_dir — never checks config.toml!
    readable = os.access(data_dir, os.R_OK)
    writable = os.access(data_dir, os.W_OK)
    ...

The config file (~/.cleveragents/config.toml) stores server.token in plaintext:

"server.token" = "tok_01HXR_test_token"

If this file has world-readable permissions (e.g., 644), the authentication token is exposed to all users on the system.

Steps to Reproduce

Run agents config set server.token "tok_01HXR_test_token"
Check that ~/.cleveragents/config.toml contains the token in plaintext
Run agents diagnostics
Observe that no warning is issued about config file permissions, even if the file is world-readable

Code Location

src/cleveragents/cli/commands/system.py:

_check_file_permissions() function — only checks data_dir, not config file
The function should also check ~/.cleveragents/config.toml permissions

Fix

Extend _check_file_permissions() to also check the config file permissions:

config_path = Path.home() / ".cleveragents" / "config.toml"
if config_path.exists():
    mode = config_path.stat().st_mode & 0o777
    if mode & 0o077:  # Group or others have any access
        checks.append({
            "name": "Config file permissions",
            "status": CheckStatus.WARN,
            "details": f"config.toml is {oct(mode)} — recommend chmod 600 (contains sensitive tokens)",
        })

Severity

Medium — Authentication tokens stored in config.toml may be exposed to other system users if file permissions are not restricted.

Subtasks

Extend _check_file_permissions() in src/cleveragents/cli/commands/system.py to stat ~/.cleveragents/config.toml
Emit CheckStatus.WARN when config file mode has group or other read/write/execute bits set (mode & 0o077)
Tests (Behave): Add BDD scenarios covering world-readable config file triggers WARN, 600 config file passes, missing config file is skipped gracefully
Tests (Robot): Add integration test verifying agents diagnostics output includes permission warning when config is 644
Update CLI reference documentation to reflect new diagnostics check
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(diagnostics): check config.toml permissions and warn when world-readable), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/diagnostics-config-file-permissions).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage >= 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/diagnostics-config-file-permissions` - **Commit Message**: `fix(diagnostics): check config.toml permissions and warn when world-readable` - **Milestone**: v3.3.0 - **Parent Epic**: #362 ## Bug Report ### Summary The `agents diagnostics` command's `_check_file_permissions()` function checks the data directory (`data/`) for read/write access, but does NOT check the permissions of the configuration file (`~/.cleveragents/config.toml`). The specification explicitly requires that diagnostics warn when the config file has overly permissive permissions, since the config file stores sensitive values including `server.token` in plaintext. ### Expected Behavior (from spec) Per specification section "Secret Management" (line 46052): > The config file should have restrictive permissions (`chmod 600`). The `agents diagnostics` command warns if config file permissions are too permissive. The diagnostics command should: 1. Check the permissions of `~/.cleveragents/config.toml` 2. Emit a `WARN` status if the file is readable by group or others (i.e., permissions are not `600` or stricter) ### Actual Behavior The `_check_file_permissions()` function in `src/cleveragents/cli/commands/system.py` only checks the data directory: ```python def _check_file_permissions() -> dict[str, Any]: """Check file permissions on the data directory.""" settings = get_settings() data_dir = settings.data_dir # Only checks data_dir — never checks config.toml! readable = os.access(data_dir, os.R_OK) writable = os.access(data_dir, os.W_OK) ... ``` The config file (`~/.cleveragents/config.toml`) stores `server.token` in plaintext: ```toml "server.token" = "tok_01HXR_test_token" ``` If this file has world-readable permissions (e.g., `644`), the authentication token is exposed to all users on the system. ### Steps to Reproduce 1. Run `agents config set server.token "tok_01HXR_test_token"` 2. Check that `~/.cleveragents/config.toml` contains the token in plaintext 3. Run `agents diagnostics` 4. Observe that no warning is issued about config file permissions, even if the file is world-readable ### Code Location `src/cleveragents/cli/commands/system.py`: - `_check_file_permissions()` function — only checks `data_dir`, not config file - The function should also check `~/.cleveragents/config.toml` permissions ### Fix Extend `_check_file_permissions()` to also check the config file permissions: ```python config_path = Path.home() / ".cleveragents" / "config.toml" if config_path.exists(): mode = config_path.stat().st_mode & 0o777 if mode & 0o077: # Group or others have any access checks.append({ "name": "Config file permissions", "status": CheckStatus.WARN, "details": f"config.toml is {oct(mode)} — recommend chmod 600 (contains sensitive tokens)", }) ``` ### Severity **Medium** — Authentication tokens stored in config.toml may be exposed to other system users if file permissions are not restricted. ## Subtasks - [ ] Extend `_check_file_permissions()` in `src/cleveragents/cli/commands/system.py` to stat `~/.cleveragents/config.toml` - [ ] Emit `CheckStatus.WARN` when config file mode has group or other read/write/execute bits set (`mode & 0o077`) - [ ] Tests (Behave): Add BDD scenarios covering world-readable config file triggers WARN, `600` config file passes, missing config file is skipped gracefully - [ ] Tests (Robot): Add integration test verifying `agents diagnostics` output includes permission warning when config is `644` - [ ] Update CLI reference documentation to reflect new diagnostics check - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(diagnostics): check config.toml permissions and warn when world-readable`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/diagnostics-config-file-permissions`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.3.0 milestone

2026-04-03 00:12:01 +00:00

freemo added a new dependency

2026-04-03 00:15:32 +00:00

#362 Epic: Security & Safety Hardening

freemo referenced this issue

2026-04-03 00:18:37 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 481 — v3.7.0 #1938

freemo commented

2026-04-03 00:19:51 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: MoSCoW/Should Have — bug or error handling improvement.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: MoSCoW/Should Have — bug or error handling improvement. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner