A cloud agent setup script installs your toolchain and dependencies before the agent starts, often with wider network access than the agent has. That makes it a supply chain entry point. Pin versions, use lockfiles, install from known registries, scan the result, and rebuild cached environments when advisories land.
Why setup deserves attention
Platforms document that setup runs differently from agent work. One lets setup scripts reach the internet to install dependencies while blocking the agent phase by default. Another lets you define setup steps in a workflow file so tools are installed deterministically, and notes that without them the agent installs by trial and error, which may be slow, unreliable, or fail for private dependencies. One vendor caches what a setup script installs so packages are available at the start of every session.
Caching is convenient, but it also means a bad install can persist. That is the same risk as a poisoned build cache.
What can go wrong
| Risk | Example |
|---|---|
| Unpinned versions | A new release changes behavior between runs |
| Install scripts | A dependency runs code at install time |
| Lookalike or compromised packages | A typo or hijack pulls the wrong code |
| Broad registry access | The setup network reaches more than needed |
| Stale cache | An old vulnerable layer keeps being reused |
| Secrets in setup | Tokens used to fetch private packages remain available |
A safer setup script
- Store it in version control with code review.
- Install from lockfiles with exact versions, and fail if the lockfile is out of date.
- Restrict setup network access to the registries you use.
- Use read-only, short-lived tokens for private registries.
- Generate an SBOM of the resulting environment and keep it with the build.
- Scan the SBOM for known vulnerabilities, and review new packages.
- Rebuild the cached environment on a schedule, and immediately when an advisory affects it.
- Confirm that setup credentials are removed or not present in the agent phase.
Who checks what
| Step | Owner |
|---|---|
| Reviewing script changes | Code owner for the repository |
| Registry allowlist | Platform or security engineering |
| Scanning the environment | Security or the team that owns the toolchain |
| Cache rebuilds | Platform team |
Try it yourself
Click through it at your own pace, or open it full screen.
Look at how direct and transitive dependencies are listed, which is the inventory you want for a setup environment.
Worked example: a pinned versus unpinned setup
An illustrative comparison.
Unpinned. The setup script runs a package install with no lockfile and installs a global tool at its latest version. Monday's run and Thursday's run install different versions of a transitive package. On Thursday a maintainer account for that package was compromised and a release shipped with a malicious install script. The script runs during setup, with registry access and any token in reach. The cached environment then carries the bad package into every session until someone notices.
Pinned. The script uses a lockfile install that fails if the lockfile does not match the manifest, and the global tool is installed at an exact version. Thursday's release is not picked up. A scheduled job later proposes a lockfile update in a pull request, which a person reviews and a scan checks before it merges. If the new version carries a known issue, the pull request is held.
The difference is not that pinning is magic. It turns a silent change into a reviewed one.
A reviewable setup file layout
| Piece | Where it lives | Reviewed by |
|---|---|---|
| Setup script | Repository, in a dedicated folder | Platform owners |
| Lockfiles | Repository root | Code owners |
| Tool versions | A single versions file | Platform owners |
| Registry allowlist | Platform configuration | Security |
| Base image reference | Pinned by digest | Platform owners |
| SBOM of the built environment | Stored with build artifacts | Security, on demand |
Pre-merge checks for setup changes
- Does the change add a new registry or host?
- Does it add a tool downloaded from a URL rather than a registry?
- Does it add a step that runs a downloaded script directly?
- Does it change token usage?
- Does it alter caching behavior?
Any yes needs an explicit reviewer sign off.
Using findings well
A scan of a large environment returns many findings. Not all matter equally. Use reachability to see which vulnerable code your own code can actually call, and prioritize those. For tools used only during setup and not present at agent time, the risk profile differs from packages loaded by your application, so label them separately.
Rebuild triggers
Rebuild the cached environment when:
- A scan reports a new serious issue in something it contains.
- A dependency in the lockfile changes.
- The base image has a security update.
- A setup script changes.
- A fixed schedule passes, such as weekly.
Evidence you can show
Keep the lockfile, the SBOM, the scan result, and the review record for each environment build. When a customer asks how your agent environments are controlled, that bundle is a concrete answer.
Where Safeguard fits
Safeguard provides SBOM and dependency scanning, plus reachability analysis to show which findings matter. Run a free scan at gold.safeguard.sh/scan.
Quick check
Should setup scripts install the latest versions?
No. Pin exact versions so each run is reproducible and reviewable.
Is a cached environment safer or riskier?
Both. It is faster and consistent, but a bad layer persists until you rebuild, so rebuild on a schedule.
Do setup-only tools need the same scrutiny as application dependencies?
Yes, because they execute with network access and sometimes credentials. They may carry a different risk profile at agent time, so track them separately but do not ignore them.
Sources
- Customize the Copilot cloud agent environment (GitHub Docs)
- Codex cloud internet access (OpenAI documentation)
- Configure cloud environments (Anthropic documentation)
Last reviewed: 19 October 2026.
