Secure Dependency Updates

Generate dependency updates on demand or on a schedule and bring policy-cleared pull requests to review.

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 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 AI agent reviews the complete Dependabot proposal, retrieves and verifies upstream package source as needed, and compares the update with its baseline. Reviews are static: they do not install the repository or run package code. The agent explicitly approves, flags, or marks the review inconclusive and explains its findings and limitations. Its verdict decides whether a PR is published; there is no second lockfile comparison or automated advisory gate.

The usage answer is informational and appears in the pull request body. Our published updater PRs do not trigger a second Superagent review. Your own CI and branch protection still apply.

This complements 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 or the Superagent MCP server:

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. If alerts cannot be read, the run reports that failure rather than inventing targets from another vulnerability database.

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

The pipeline has three stages:

Dependabot generates the proposed dependency files in an isolated sandbox using the repository's pinned base commit. Superagent preserves those files unchanged.
AI agent reviews the complete proposal in a separate environment. It investigates package source and repository usage and returns an explicit approval, security concern, or inconclusive verdict with its explanation.
PR is created or refreshed only when the agent approves. Its body includes the agent's assessment. A GitHub check records that same verdict for the exact candidate commit. There is no second resolution, custom lockfile comparison, automatic advisory decision, or post-publication re-review.

Sandboxes are cleaned up after their work finishes. Runs do not automatically close other PRs based on a custom version comparison.

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 <name> to v<version>. Commits are authored by Superagent. Automerge is never enabled.

Withheld updates

A candidate is not published, and the run records why, when:

flagged: the AI agent identified a material security concern.
scanner-incomplete: the AI agent returned an inconclusive verdict or did not return a valid completed report.
scanner-failed: the review could not start or its infrastructure failed.
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 AI agent investigates the ecosystems Dependabot reports; an application scanner allowlist does not decide publication. If it cannot obtain the required source or complete its review, it reports an inconclusive verdict. Updater jobs currently receive repository Git credentials only; private package-registry credentials are not forwarded.

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 for the payload and signature format.