> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt. Generate dependency updates on demand or on a schedule and bring policy-cleared pull requests to review. # Secure Dependency Updates Secure Dependency Updates works like GitHub Dependabot security and version updates, with two differences: Superagent opens the pull requests automatically, and every candidate passes a supply-chain scan in an isolated sandbox before its pull request is published. Updates are generated by pinned, unmodified [dependabot-core](https://github.com/dependabot/dependabot-core) running in a Superagent sandbox. Before a pull request is created or refreshed, a Superagent agent evaluates the exact candidate commit in a separate sandbox and answers two questions: - Does the new version contain dangerous install/runtime behavior, including credential theft and malicious code, or known vulnerabilities? - Is this dependency used? The agent traces direct and transitive usage through the repository's source, configuration, developer tooling, and CI, and cites the files it found. Supply-chain attacks are the first investigation priority: changed dependency payloads, install/import hooks, credential theft, unexpected connections, hidden loaders, persistence, worms, and social engineering or agent manipulation. The agent follows suspicious behavior beyond known signatures; this path does not include a live threat-intelligence feed. The agent inspects published artifacts and compares old and new versions with controlled install/runtime tests. Exact-version advisories come from OSV. The model uses the same OpenRouter credentials and model settings as repository red teaming. GitHub and model-provider credentials stay on the application server, outside the package-execution sandbox. The usage answer is informational. It appears as the **Is this dependency used?** row in the pull request body (**Yes, in production code**, **Yes, development/CI only**, or **No**) but never blocks publication, just as Dependabot does not skip an alert because the vulnerable function looks unused. Published pull requests still trigger the normal GitHub webhooks, including an independent dependency assessment before merge. This complements [Supply chain scanning](https://www.superagent.sh/docs/security-workers/pr-security/supply-chain-scanning). ## Enable scheduled updates Open **Repository**, select a repository, and find **Secure Dependency Updates** in its settings. Choose a scope: - **Vulnerabilities** (default) - **Version updates** - **All updates** Then choose one schedule: - **Off** disables new scheduled update runs. This is the default. - **Daily** checks once per day. - **Weekly** checks once per UTC week. - **Monthly** checks once per UTC month. The schedule is repository specific. Turning the setting off does not close existing update pull requests. Each live run on a private repository costs **5 credits** when it starts, whether scheduled or manual, even if it fails or finds no updates. Public repository runs and dry-runs cost no credits. Private free-plan runs cannot start when fewer than 5 credits remain; a queued manual run can also fail if other usage consumes the remaining credits before it begins. ## Run updates manually Organization owners can open a repository and select **Run now** in the **Dependency updates** section header. The button uses the current scope. You can run updates while the schedule is **Off** without enabling or changing the schedule. The section lists recent runs with their published, refreshed, withheld, and failed counts. For automation, use the [Dependency Updates API](https://www.superagent.sh/docs/api/dependency-updates) or the [Superagent MCP server](https://www.superagent.sh/docs/mcp): - `POST /api/v1/repositories/{repositoryId}/dependency-updates` starts a run. The optional `scope` is `vulnerabilities`, `versions`, or `all`; omit it to use the repository's saved scope. - `GET /api/v1/dependency-updates/{runId}` polls the run status. - MCP `trigger_dependency_updates(repository_id, scope?)` starts a run, and `get_dependency_update(run_id)` retrieves it. The repository must belong to the API key's organization and have an active Superagent Security GitHub App installation. An already active run returns `409 conflict`. An inactive repository or installation, or a repository or run outside the organization, returns `404 not_found`. A `202 Accepted` response means the run is queued, not that a pull request has been published. Status progresses through `queued` and `in_progress` to `completed` or `failed`. Even a completed run can produce no pull requests. The REST polling response includes a structured `summary` with alert, job, candidate, publication, and withheld counts. Use `dependency_update.published` to react when an update actually reaches GitHub. ## Update scopes ### Vulnerabilities Superagent reads the repository's open Dependabot alerts, the same list shown under **Security → Dependabot** in GitHub, and creates one security update job per vulnerable dependency and manifest directory. Like Dependabot security updates, a job upgrades the dependency to the lowest version that fixes every open alert for it, updating a parent dependency when a transitive fix requires it. Alerts without a patched version cannot produce a pull request. This requires the Superagent Security GitHub App's **Dependabot alerts: Read** permission. When alerts are unavailable, Superagent falls back to the repository's dependency graph SBOM checked against OSV. SBOM entries carry no manifest location, so every matching manifest directory is targeted. ### Version updates Superagent runs dependabot-core version update jobs for direct dependencies. When `.github/dependabot.yml` exists, its `package-ecosystem`, `directory` or `directories`, `allow`, `ignore`, `groups`, `versioning-strategy`, and `open-pull-requests-limit` settings are honored; schedules are controlled by Superagent. Without a configuration file, every detected manifest directory is checked with a limit of five open pull requests. Transitive packages can still change when the package manager resolves the lockfile for a direct update. ### All updates Security and version jobs run in the same repository run. Both kinds of proposals receive the same assessment before publication. ## How an update is created For each repository run, Superagent: 1. Pins the default branch commit, discovers manifests, and reads open alerts. 2. Starts dependabot-core in its own sandbox with a short-lived GitHub App token restricted to that repository. The updater only reads the repository; it never pushes branches or opens pull requests itself. 3. Collects each job's proposed manifest and lockfile changes. Proposals that land on the same branch are merged into one pull request. 4. Builds the candidate commit and sends an immutable repository snapshot to a separate assessment sandbox. Provider and GitHub credentials stay on the application server. 5. Downloads the published package artifacts, verifies supported lockfile bindings, and compares install/runtime behavior with the previous version. Outbound network access is blocked before agent-directed execution. 6. Checks whether the alert being fixed applies to the repository using source call sites, configuration, entry points, build/test commands, and CI. 7. Points the update branch at the scanned commit and creates or refreshes its pull request. The body contains the package changes, advisory details, assessment, and release notes. 8. Closes older single-dependency Superagent pull requests that a newer version supersedes, then cleans up the sandboxes. Branches use the `superagent/deps/` prefix and stay stable per dependency and directory, so later runs refresh the existing pull request instead of opening a duplicate. Titles use `chore(bump): update dependency to v`. Commits are authored by Superagent. Automerge is never enabled. ## Withheld updates A candidate is not published, and the run records why, when: - `flagged`: the scan found malicious behavior or an applicable vulnerability in the new version. - `scanner-incomplete`: artifact inspection, installation, or runtime coverage could not be completed. - `scanner-failed`: the assessment sandbox failed. - `scanner-unsupported`: the ecosystem has no artifact scanner yet. - `base-moved` or `commit-failed`: the default branch changed or the candidate commit could not be created. A withheld candidate is retried on the next run. ## Package managers dependabot-core runs for npm, pnpm, and Yarn (`npm`), Bun, pip, Poetry, Pipenv, and uv, Bundler, Go modules, Cargo, Composer, Maven, Gradle, NuGet, Pub, Hex, Swift, GitHub Actions, Docker, and Terraform. Generated, vendored, and build directories such as `node_modules`, `vendor`, `target`, and `dist` are ignored during discovery. The supply-chain scanner currently covers npm, PyPI, Go, RubyGems, and crates.io artifacts. Updates in other ecosystems are discovered but withheld as `scanner-unsupported` until their artifacts can be scanned. Exact byte binding supports npm package-lock v2/v3, pnpm v9, and Cargo.lock checksums; other lockfile formats use registry identity checks. Private registries remain unsupported in this release and cause the affected job to fail without a pull request. Results describe the observed Linux environment and documented coverage; they do not guarantee the absence of dormant or environment-specific malicious behavior. Review the assessment and required checks before merging. ## Publication events To trigger your own automation when an update reaches GitHub, subscribe an organization webhook to `dependency_update.published`. The event includes the repository, the persisted dependency update pull request ID, title, and pull request URL. The same publication also creates a home-page notification for organization owners. See [Webhooks](https://www.superagent.sh/docs/webhooks) for the payload and signature format. ## Next steps - [Understand supply chain scanning](https://www.superagent.sh/docs/security-workers/pr-security/supply-chain-scanning) - [Subscribe to published updates with Webhooks](https://www.superagent.sh/docs/webhooks) - [Validate dependency updates with Devin](https://www.superagent.sh/docs/use-cases/validate-dependency-updates-with-devin) --- Source: https://www.superagent.sh/docs/security-workers/secure-dependency-updates Index: https://www.superagent.sh/llms.txt