fix(security): require explicit SANDBOX_ALLOW_FULL_ACCESS to enable FullAccess policy

[zmanian]

Supersedes #516.

Why this replacement exists:

• the original PR branch lives on difflabai/ironclaw
• this credential could not push required rebases back to that fork
• this branch carries the same FullAccess hardening rebased onto current staging

Scope preserved from #516:

• require explicit SANDBOX_ALLOW_FULL_ACCESS=true opt-in
• preserve audit visibility for FullAccess execution
• keep the updated config/test coverage aligned with current staging

Please review/merge this replacement instead of the original blocked PR.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the security posture of the sandbox feature by introducing a mandatory double opt-in for the highly privileged FullAccess policy. Previously, setting SANDBOX_POLICY=full_access was sufficient to enable direct host command execution. Now, users must also explicitly set SANDBOX_ALLOW_FULL_ACCESS=true, preventing accidental or unintended execution of commands outside the sandbox environment. This change includes robust validation, automatic policy downgrading, and improved logging for better auditing.

Highlights

• Double Opt-in for FullAccess Policy: Introduced a new configuration option, SANDBOX_ALLOW_FULL_ACCESS, which must be explicitly set to true to enable the highly privileged FullAccess sandbox policy. If FullAccess is requested without this explicit opt-in, the policy is automatically downgraded to WorkspaceWrite.
• Enhanced Security and Auditability: Implemented runtime checks to enforce the SANDBOX_ALLOW_FULL_ACCESS requirement, preventing accidental host-level command execution. Added warning logs for FullAccess executions to improve audit visibility, detailing the binary and current working directory.
• Comprehensive Test Coverage: Added new unit tests to verify that FullAccess policy is correctly downgraded or blocked when SANDBOX_ALLOW_FULL_ACCESS is not set, and that it functions as expected when explicitly enabled.
• Configuration and Documentation Updates: Updated .env.example with the new SANDBOX_ALLOW_FULL_ACCESS variable and clarified documentation for the FullAccess policy, highlighting its 'BLAST RADIUS' and the double opt-in requirement.

Changelog

• .env.example
  • Added SANDBOX_ALLOW_FULL_ACCESS variable with a default of false and detailed comments explaining its purpose and implications.
  • Included other Docker Sandbox related variables for clarity.
• src/config/sandbox.rs
  • Added allow_full_access boolean field to SandboxModeConfig struct.
  • Updated Default implementation to set allow_full_access to false.
  • Modified from_env to parse SANDBOX_ALLOW_FULL_ACCESS from environment variables.
  • Implemented logic in to_sandbox_config to downgrade FullAccess policy to WorkspaceWrite if allow_full_access is false, logging a warning.
  • Added allow_full_access to the SandboxConfig conversion.
  • Added new unit tests (test_full_access_downgraded_without_allow, test_full_access_allowed_with_explicit_opt_in, test_non_full_access_policy_unaffected, test_readonly_policy_unaffected) to verify the new behavior.
• src/sandbox/config.rs
  • Added allow_full_access boolean field to SandboxConfig struct with extensive documentation on its security implications.
  • Updated Default implementation to set allow_full_access to false.
  • Expanded documentation for SandboxPolicy::FullAccess to detail its "BLAST RADIUS" and the requirement for SANDBOX_ALLOW_FULL_ACCESS=true.
• src/sandbox/manager.rs
  • Modified execute method to perform a runtime check for self.config.allow_full_access when policy is FullAccess. If false, it returns a SandboxError::Config.
  • Added tracing::warn! log for FullAccess execution, including the binary name and current working directory, to enhance auditability.
  • Updated SandboxManagerBuilder with a new allow_full_access method and enhanced documentation for the policy method, clarifying the double opt-in requirement.
  • Modified existing tests (test_direct_execution_success, test_direct_execution_truncates_large_output) to explicitly set allow_full_access: true.
  • Added new unit tests (test_direct_execution_blocked_without_allow, test_builder_full_access_without_allow_returns_error) to confirm that FullAccess is blocked without explicit allowance.

Activity

• This pull request supersedes and replaces a previous, blocked PR (fix(security): require explicit SANDBOX_ALLOW_FULL_ACCESS to enable FullAccess policy #516).
• The original PR branch was on a different fork, preventing rebases.
• This branch carries the same FullAccess hardening rebased onto the current staging branch.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a critical security enhancement by requiring an explicit opt-in (SANDBOX_ALLOW_FULL_ACCESS=true) to use the FullAccess sandbox policy. The changes are well-implemented with a defense-in-depth approach:

1. At configuration time, if FullAccess is set without the explicit opt-in, the policy is safely downgraded to WorkspaceWrite with a log message.
2. At execution time, there's an additional check that returns an error if FullAccess is attempted without being allowed, preventing misuse through direct API calls.
   The changes include updated documentation, configuration examples, and comprehensive tests covering the new logic. My feedback includes a minor suggestion to adjust a log level for better semantic accuracy.

[gemini-code-assist]

The use of tracing::error! here might be too strong, as the situation is handled gracefully by downgrading the policy to WorkspaceWrite. An error log level typically indicates a failure that prevents an operation from completing, whereas this is a preventative measure for a misconfiguration. Using tracing::warn! would be more appropriate to alert the operator of the misconfiguration and the automatic downgrade without implying a failure.

Suggested change

	tracing::error!(
	tracing::warn!(