anthropics / anthropics/claude-code-action

Enhance security doc: sandbox credential isolation for fork PR workflows

Open
#1,541 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
8.9k
Forks
2.1k
Avg merge
3d 9h
Merged PRs (30d)
10

Description

## Context

We implemented a `workflow_run`-based CI pipeline that runs Claude Code on fork PR code with access to GCP/Vertex AI secrets (eval execution requiring API auth). While following the `--add-dir` safe pattern from [security.md](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md), we found three gaps where the doc could be strengthened.

## Proposed Enhancements

### 1. Recommend `sandbox.credentials.envVars` alongside `--add-dir`

The current safe pattern for fork PRs shows:

```yaml
- uses: actions/checkout@v6 # base branch at workspace root
- uses: actions/checkout@v6
with:
ref: ${{ github.event.pull_request.head.sha }}
path: pr-head
- uses: anthropics/claude-code-action@v1
with:
claude_args: "--add-dir pr-head"
```

This protects the workspace root (trusted CLAUDE.md/config) but doesn't address credential exfiltration via Bash subprocesses. A prompt injection in the fork's code can still run `env | grep` to extract secrets.

Claude Code's `sandbox.credentials.envVars` with `"mode": "deny"` solves this — it strips specified env vars from sandboxed Bash subprocesses while the Claude Code runtime retains access for API authentication (confirmed in [Claude Code sandboxing docs](https://code.claude.com/docs/en/sandboxing#protect-credentials), available since v2.1.187).

**Suggested addition** — extend the safe pattern example:

```yaml
- uses: actions/checkout@v7 # base branch at workspace root
- uses: actions/checkout@v7
with:
ref: ${{ github.event.pull_request.head.sha }}
path: pr-head
allow-unsafe-pr-checkout: true
- uses: anthropics/claude-code-action@v1
with:
claude_args: "--add-dir pr-head --settings /path/to/sandbox-settings.json"
```

With a sandbox settings file containing:

```json
{
"sandbox": {
"enabled": true,
"credentials": {
"envVars": [
{ "name": "GOOGLE_APPLICATION_CREDENTIALS", "mode": "deny" },
{ "name": "AWS_SECRET_ACCESS_KEY", "mode": "deny" }
]
}
}
}
```

This gives layered defense: trusted workspace root + credential isolation from subprocesses.

### 2. Update `--add-dir` example for `actions/checkout@v7`

The safe pattern example uses `actions/checkout@v6`. As of v7 ([backported to all supported major versions on July 20, 2026](https://github.blog/changelog/2026-06-18-safer-pull_request_target-defaults-for-github-actions-checkout/)), the checkout guard blocks fork PR refs in `workflow_run` and `pull_request_target` workflows **regardless of the `path:` parameter**. The subdirectory checkout requires `allow-unsafe-pr-checkout: true`.

The example should use `@v7` with `allow-unsafe-pr-checkout: true` on the PR checkout step, and a note explaining that the flag is needed even for subdirectory checkouts because the guard doesn't distinguish workspace root from subdirectories.

### 3. Document `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1` as a standalone feature

The doc currently mentions env scrubbing only under the `allowed_non_write_users` section:

> When set, Claude does a best-effort scrub of Anthropic, cloud, and GitHub Actions secrets from subprocess environments.

This makes it look like a side effect of `allowed_non_write_users`. In practice, `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1` works independently — the `action.yml` checks `env.CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` first, falling back to `allowed_non_write_users` only when unset. It's useful for any `workflow_run` workflow processing fork PR code, even with write-access actors.

Two things worth documenting:
- It can be set as a standalone env var in any workflow, independent of `allowed_non_write_users`
- It requires `bubblewrap` and `socat` on Linux runners — without them, Claude Code fails at startup

## References

- [GitHub Changelog: Safer pull_request_target defaults for checkout](https://github.blog/changelog/2026-06-18-safer-pull_request_target-defaults-for-github-actions-checkout/)
- [Claude Code Sandboxing: Protect credentials](https://code.claude.com/docs/en/sandboxing#protect-credentials)

Contributor guide

Open the contributing guide

Research direction

Start with docs/security.md and compare its fork PR checkout example with the checkout v7 guidance and sandbox credential settings described here. Read action.yml to verify how CLAUDE_CODE_SUBPROCESS_ENV_SCRUB is selected and which Linux dependencies are required. Done means the security documentation covers all three enhancements with accurate examples, standalone env-scrubbing guidance, and the stated startup requirements.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, json, yaml
Domain
ci-cd, documentation, security
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.