Dashboard dependency upgrades

Private-package and container remediation extends the review queue with organization advisory verification and rebuilt-image evidence.

For cross-repository campaigns and refreshing expired or conflicting fixes, see Security Workflows. Campaigns reuse the profiles and isolated upgrade worker configured here.

Package impact and workspace parent fixes

Open Package Impact in the sidebar to search a package name, CVE or advisory ID across the latest saved inventory for each repository and branch. Results show installed versions, workspace membership, assigned issue owners, issue status and prepared fixes. Open the scan for its evidence or review the saved fix. Inventory dates and commits are shown explicitly; this is not deployment discovery. Search is paginated after matching and reports partial coverage when inventory, issue, history or response-processing limits are reached.

Fresh npm and uv workspace inventories attribute nested packages to the direct dependencies of each member. When one direct parent unambiguously introduces an advisory, Verify upgrade offers that parent. Enter a reviewed parent version when the advisory does not supply one; a child's fixed version is never used as the parent's version. Verification checks the whole shared lockfile: retaining the advisory in another member prevents a passing parent fix. Groups still require direct advisories. Rescan older inventories to obtain these paths.

Automatic preparation

In Security settings, select a repository policy and enable Automatic fix preparation. Choose an operator-configured profile for the same repository and branch, critical/high severities, and a daily cap of 1–5 jobs. The dedicated upgrade worker checks these policies once a minute when idle. It requires a saved source inventory with a commit, an active administrator who enabled the policy, an active unsnoozed issue and a known newer target version.

Preparation is deduplicated across rescans, administrators and worker restarts by repository policy, profile, source commit, package and target version. It shares the five-active-upgrades organization limit, stops if the branch moved since inventory, and does not retry failed/cancelled attempts automatically. Rescan changed code or start a manual job to retry. Disabling the policy or revoking its administrator stops queued/running automatic preparation.

Prepared jobs are labelled automatic in the existing upgrade review screen. No policy approves publication: an administrator must review the exact diff and explicitly create its draft PR. Existing expiry and publication checks apply.

Private npm and Python registries

Hosted npm and uv profiles can resolve approved private dependencies while fixing public dependency advisories. Configure one private HTTPS registry per profile. Credentials are supplied separately on the dedicated worker; never put a token in the profile JSON, repository, URL, dashboard or test command. The web process needs the same profile configuration but does not need the registry token.

Add these fields to an npm profile (including existing repository/test fields):

{
  "registry": {
    "url": "https://packages.example.com/npm/",
    "packages": ["@company/*"]
  },
  "registry_token_env": "AEGIS_UPGRADE_COMPANY_REGISTRY_TOKEN"
}

The worker environment variable holds a read-only registry token. npm supports approved scopes and package-lock.json v2/v3, including workspaces. An optional repository .npmrc may contain only exact approved scope-to-registry mappings, such as @company:registry=https://packages.example.com/npm/; repository auth, environment substitutions and other npm overrides are refused. Tokens are scoped to the configured registry host/path in a temporary root-only config that is removed after every package-manager command.

For a uv profile, use normalized exact package names, including private transitive packages, and an optional nonsecret username:

{
  "registry": {
    "url": "https://packages.example.com/simple/",
    "packages": ["company-library", "company-utils"],
    "username": "__token__",
    "artifact_url": "https://packages.example.com/files/"
  },
  "registry_token_env": "AEGIS_UPGRADE_COMPANY_REGISTRY_TOKEN"
}

The root pyproject must declare every approved private package on the named explicit index, preventing fallback to a public package with the same name:

[[tool.uv.index]]
name = "aegis-private"
url = "https://packages.example.com/simple/"
explicit = true

[tool.uv.sources]
company-library = { index = "aegis-private" }
company-utils = { index = "aegis-private" }

uv receives credentials through its named-index environment variables only in the package-manager process. Private artifacts must be hashed and remain on the same approved origin; artifact_url defaults to that origin's root. Resolution does not execute builds or install hooks. Offline guest tests receive no registry credentials. See uv indexes and npm credential scoping.

Private package versions appear in inventory and Package Impact, but are not queried against public OSV. The review screen lists the unchecked private versions separately. This feature does not supply a private advisory feed or claim those packages are vulnerability-free. Whole-scan advisory coverage stays partial, so it cannot falsely confirm all issues fixed. Custom HTTPS registries are supported; private packages hosted on the public npm/PyPI endpoints, private registry mirrors of public packages, cross-origin artifact hosts and arbitrary repository credential configuration are outside this bounded workflow.

After deploying these changes, rebuild/pin the runner image, configure the registry profiles and worker token variables, and restart the API and dedicated worker with matching profile/image configuration. Upgrade Setup reports registry scope and worker readiness without exposing credentials. No database migration is required for these settings.

An organization owner or administrator can open a direct npm, Python/uv, pnpm, Yarn Classic, or Go OSV finding in a saved repository scan, choose Create upgrade PR → Verify in dashboard, select a configured test profile and enter an exact newer stable version. Verification does not publish anything. Progress, cancellation and verified diffs are saved in the database; Jobs → Dependency upgrades reopens them after a reload.

Review the diff and check its confirmation before selecting Create draft PR. The broker publishes only the reviewed manifest and lockfile. It checks the exact base commit again and never merges. Review repository CI before merging the draft. Verification expires after two hours. If publication fails or its worker stops, review the retained diff and retry publication on the same job while it is fresh. Its deterministic branch recovers an existing matching draft rather than creating another. If verification has expired, inspect any retained branch or draft before starting a new job.

Bulk verification

On saved scan results, choose Verify dependency fixes to select up to five eligible packages across configured profiles. Each has its own target version, durable request ID, test result, and diff. A failed or uncertain request can be retried without duplicating its job. Successful jobs remain saved if another request fails.

Select Combine compatible npm, uv or Cargo fixes into one PR for two–five directly affected packages from one profile/project. A group resolves all pins together, runs the configured commands once, produces one reviewed diff, and publishes one draft. Every selected package must lose its advisories across the whole shared inventory, without introducing another advisory. Parent/transitive recommendations and other managers use separate jobs. Retrying preserves the exact group and request ID.

uv groups can span normal dependencies, dependency groups and optional extras; the runner installs the union of the selected groups/extras into one environment. Cargo groups can combine member-local and inherited root declarations. Both standalone projects and supported shared workspaces can use grouped fixes.

Supported hosted scope

Hosted execution supports configured public or private GitHub, GitLab and Azure DevOps repositories. Choose manager in each profile (default npm):

ManagerSupported scope
npmOne direct dependency, devDependency or optionalDependency; package-lock or npm-shrinkwrap v2/v3. Groups and shared workspaces use package-lock.json only.
uvOne direct PyPI dependency, dependency group or optional extra; static pyproject.toml and uv.lock v1. Set workspace: true for a selected member and root shared lock. Public or explicitly approved private wheels, no first-party install/build, no interpreter download. Tests use the shared installed virtual environment.
pnpmOne direct registry dependency; pnpm v10 with lockfile v9. Set workspace: true for a root shared lock and a selected member in project.
yarnOne direct Yarn Classic dependency in package.json and a v1 yarn.lock. Yarn 1.22.22 is in the runner image.
goOne direct public module with stable vX.Y.Z versions in go.mod/go.sum. Local Go 1.25.14, public proxy and checksum DB; no replace/exclude, workspaces, vendor tree, private modules, CGO, or toolchain downloads. Tests use the predownloaded cache offline. The version field is prefilled with vX.Y.Z. An advisory installed by one direct module offers that module.
mavenOne direct coordinate in a single-module pom.xml; public Maven Central dependencies. No parents, custom build plugins, profiles, extensions or repository overrides. Maven and JDK 26 are bundled.
nugetOne direct stable package in an SDK-style Microsoft.NET.Sdk project and packages.lock.json. Set manifest to the exact .csproj filename. Literal allowlisted properties and PackageReference items only; no custom MSBuild logic. The bundled .NET 10 SDK must support the selected target framework.
cargoOne direct crates.io dependency in Cargo.toml and Cargo.lock. Set workspace: true for a root shared lock and selected member. Alternate registries, git dependencies, Cargo configuration and repository toolchain overrides are excluded. Rust and Cargo are bundled.

pnpm workspaces support up to 100 named members, root pnpm-workspace.yaml containing only packages, and bounded paths/single-level globs. Local workspace:*, workspace:^ and workspace:~ references must point to declared members. Only the selected member's manifest and root lock can change. Other workspace members that retain an advisory for the selected package prevent a passing verification.

npm and Cargo shared workspaces also accept up to 100 tracked members with literal paths or single-level globs, and at most 500 registry dependencies. npm validates root lockfile links against all member manifests; overrides, nested workspaces, bundles and devEngines are unsupported. Cargo accepts declared local member path dependencies, inherited workspace.package metadata and workspace.dependencies. An inherited dependency is pinned in the root table, affecting every member that inherits it; other dependencies are pinned in the selected member. The reviewed artifacts include the root manifest, selected member manifest and shared lockfile. Package names and effective versions must be literal. Patch, replace, nested workspaces and alternate registries remain unsupported.

uv workspaces accept static members with bounded literal paths or single-level globs and exclusions, and explicit { workspace = true } local sources. External paths, git sources, dynamic metadata and unapproved indexes are rejected. Only the selected member's requirement and root lock can change; the root manifest is also retained as review evidence. Verification checks all locked public packages and rejects any remaining advisory for the selected dependency anywhere in the workspace. Online synchronization installs public wheels into the root .venv without installing or building workspace packages. Configured tests run from the selected member, offline and unprivileged, using that shared environment. A direct advisory is required; parent/transitive upgrade suggestions are not supported for uv workspace profiles.

For broader Maven scan coverage, run aegis maven-inventory --pom path/to/pom.xml. This copies a validated plain POM into a temporary directory and runs the pinned Maven dependency-tree plugin, using public Central. The adjacent aegis-maven-inventory.json records the POM digest and all-scope tree. A rescan includes transitive artifacts and their direct introducers. Stale/malformed trees fall back to direct dependencies with a warning. Imported trees remain explicitly partial evidence: Maven does not enforce them as a lockfile, and they cannot alone confirm a merged fix. Regenerate after dependency changes. Parents, modules, custom build plugins and repository overrides need a separate workflow.

The package must appear as direct and resolved in saved inventory; rescan older inventories that lack this metadata. Approved private npm/uv registries use the dedicated workflow above. Resolution overrides, repository package-manager hooks and install/build lifecycle scripts remain excluded. Gradle, Bundler, Composer, Poetry, and Pipenv use the CLI upgrade adapters. Maven, NuGet and Cargo hosted profiles currently offer directly affected packages. Their broader CLI workflows remain available for projects outside these restrictions.

Compiled profiles download dependencies before network removal. Maven pins its resolution plugin and prefetches lifecycle plugins; Cargo only updates and fetches. NuGet restores with a fresh intermediate directory and disabled directory imports, so restored package build targets run only during offline guest tests. Example test arrays are ["mvn","-B","test"], ["cargo","test","--locked","--offline"] and ["dotnet","test","--no-restore","App.csproj"]. Maven uses an offline local cache automatically. Tests must fit the container limits and use predownloaded framework assets. scripts/check_compiled_upgrades.py IMAGE_ID exercises real SDK upgrades with synthetic advisories, protected artifacts and offline guest tests.

Test commands come from an administrator's deployment configuration. Users cannot submit shell commands, repository paths, runner images or credentials through the API. Tests run without network access, as UID/GID 10001, after public dependency resolution and advisory checks. A test suite that downloads fixtures, writes tracked files or requires install scripts needs preparation before it can use this runner. The verified manifest and lockfile must be ordinary nonexecutable Git blobs.

Configure the worker

GitHub profiles keep the default provider: "github". For GitLab, set provider: "gitlab", base_url: "https://gitlab.com" and repository: "group/subgroup/project". For Azure, set provider: "azure-devops", base_url: "https://dev.azure.com/organization" and repository: "Project/_git/Repository" (spaces encoded as %20). Operator host allowlists from the existing provider integrations still apply. Set private: true only for private repositories; a visibility change requires a new configuration and verification.

All GitLab/Azure verification uses the credential broker, including public repositories. Its dedicated token_env must be present on the worker for readiness. Grant GitLab repository read/write and merge-request API access, or Azure repository read/contribute/create-branch/pull-request permissions, scoped to the configured repository. Provider credentials never reach the runner. GitLab draft merge requests and Azure draft PRs use the same reviewed-artifact and two-hour expiry checks as GitHub. Retries recover only the exact original commit/tree; moved bases or edited job branches require fresh verification. Lifecycle polling shows commit-status evidence and matching merged scans, with missing/truncated status evidence left pending or unavailable. It is not a check that every provider branch policy has been satisfied.

  1. Apply migrations with flask --app api.server:create_app db upgrade.
  2. Build the separate runtime: docker build -f deploy/upgrade-runner.Dockerfile -t aegis-upgrade-runner ..
  3. Read its immutable image ID with docker image inspect aegis-upgrade-runner --format '{{.Id}}'.
  4. On the runner host, check what tests get inside it: python scripts/check_runner_isolation.py <image ID>.
  5. Configure the same image and profiles in the API and the dedicated worker.
  6. Start python -m upgrade_worker on the dedicated Docker runner host.

Example configuration (replace the repository and the organization ID, which Settings shows under Account):

export AEGIS_UPGRADE_RUNNER_IMAGE='sha256:REPLACE_WITH_64_HEX_IMAGE_ID'
export AEGIS_UPGRADE_PROFILES='[
  {"id":"web-tests","label":"Web package tests","org_id":1,
   "repository":"example/web","base":"main","project":".",
   "tests":[["npm","test","--","--runInBand"]],"timeout":900,
   "token_env":"AEGIS_UPGRADE_WEB_TOKEN"}
]'
python -m upgrade_worker

Use the production API environment, including DATABASE_URL, authentication configuration and AEGIS_SKIP_CREATE_ALL=1. A remote worker must share the API's production database. SQLite is suitable for a local single-host evaluation. Profiles bind an exact repository, base branch, project and test commands to one organization. project is . or a repository-relative directory. Tests are argv arrays, not shell strings. Timeouts are 60–1800 seconds. Configuration changes invalidate queued plans for the worker's configured organizations; start a fresh verification and restart workers after changing their environment. The API accepts work only when a worker has a recent heartbeat for the same configuration.

For draft publishing, set the profile's dedicated token variable only on the worker. Use a token restricted to that repository with Contents and Pull requests write permission. Keep it out of the API environment and runner image. Verification of public GitHub repositories works without a publishing token; requesting a draft then explains that the publishing worker is unavailable. Store secrets through your deployment's secret manager. Do not commit them to profile JSON or source control.

Set private: true for a private GitHub repository. Its dedicated token is also required for source access. The broker clones the configured branch with the token in a short-lived Git environment, checks the exact base and replaces transport configuration before making a bounded snapshot. The container receives code and credential-free Git objects; no token or credential helper is copied. Private snapshots reject links, submodule/alternate-object dependencies and oversized sources (20,000 files, 64 MiB per file, 256 MiB total). Host scratch quotas still apply while Git fetches. Private diffs remain organization data in the AEGIS database.

Jobs → Upgrade setup shows only your organization's profiles, worker and publishing readiness, and the latest attempt. It explains missing configuration, stale heartbeats and missing credentials. Readiness is not a substitute for the host isolation probe or a first verification against your actual repository.

Published jobs are checked at most every two minutes when the worker is idle. The token needs read access to repository Checks and Commit statuses to display CI evidence. A changed PR head invalidates the claim that its current contents are the reviewed artifact. Merge status is separate from fix confirmation: run or schedule a complete advisory rescan of the base branch to confirm the fix.

Runner deployment and failure recovery

Run the controller on a dedicated host with scratch disk quotas. Each job uses a fresh labeled Docker container and named volume, read-only image, one CPU, 1 GiB memory, 64 PIDs, per-file limits and a timeout. Docker named volumes do not provide an aggregate disk quota; configure that at the runner host/storage layer before enabling untrusted repositories. The runtime receives no host mounts, Docker socket, database credentials, application secrets or GitHub token. A trusted supervisor disconnects its network before repository tests run and protects Git, tracked files and control artifacts from guest writes.

The worker claims jobs with database state transitions and refreshes heartbeats during verification and GitHub publication. The worker rechecks the requester's active organization membership and owner/admin role before execution and at each checkpoint. Revoking that access stops later operations; it cannot undo a GitHub write already in progress.

After a worker stops reporting for three minutes, another worker marks verification failed or publication retryable. Running cancellation takes effect at the next checkpoint; publication cannot be cancelled once external writes start. Container and volume cleanup names only resources created for that job. If Docker cleanup itself fails, an operator must inspect its aegis.upgrade label and remove the retained resource.

The API limits ordinary requests to five active jobs per organization, with concurrent requests potentially racing that queue check. Provision runner capacity and host quotas independently of the queue limit. Jobs and reviewed public source diffs remain in the application database under its normal backup/retention policy. Account erasure removes the user's requests; data export includes their safe job summaries and reviewed diffs. Removing a request prevents later worker checkpoints from publishing it, but does not undo a GitHub write already in progress.

The Tests workflow stands in for GitHub and for Docker. It exercises auth, tenant and state boundaries, artifact validation, the flags the worker passes to Docker and the supervisor's steps, but not what a kernel enforces. The Runner isolation workflow (.github/workflows/runner-isolation.yml) builds this image and runs scripts/check_runner_isolation.py, which creates a container with the worker's own flags and network hand-off and checks from inside it that tests have no network, run as UID/GID 10001 without capabilities, get the CPU, memory, PID and file limits above, and cannot read the plan, the supervisor's control directory or Git state, or change tracked files. It runs when the runner changes and on demand. Limits depend on the host's kernel and Docker configuration, which is why step 4 of the setup runs the same check on your runner host. It needs Docker and the requests pin from requirements.txt, nothing else.

Before enabling a production profile, also run it against a disposable repository, review its exact diff and check draft creation with your own scoped token. A passing verification reports removed and remaining OSV advisories; it does not claim every vulnerability was fixed.

Automatic verification after merge

The dedicated worker polls published AEGIS upgrade PRs. After GitHub reports a merge, it queues a durable full-repository scan of the configured base branch. Enable AEGIS_OSV_ENABLED=true on that worker. Private repositories reuse the existing credential broker; tokens stay out of scan job payloads and source code is not executed during verification scans.

Fix progress shows the verification job and its queued, running, retry-wait or blocked state. Failed or incomplete evidence gets at most three attempts per merge, with five-minute and ten-minute waits before attempts two and three. Cancelled verification is not automatically restarted; use Repository Scan now for an intentional new attempt. Five active managed scans per organization defer further automatic requests.

A successful merge or completed job alone is insufficient. Confirmation requires a complete advisory scan of the merge commit or a verified descendant, in the same organization, repository and base branch. The scan must inventory resolved dependencies from the upgraded project’s lockfile (or go.mod); an ignored or removed dependency file leaves verification unconfirmed. Raw advisory IDs are recorded before rule suppression, so a transitive or hidden advisory cannot produce a false confirmation. Older scans without that evidence require a fresh scan. Still-detected advisories remain visible; they do not trigger endless automatic scans. GitHub or OSV outages leave verification unconfirmed.

A plain Maven POM supplies direct declarations, not a complete resolved dependency tree. Static scans and imported Maven trees remain partial. For published Maven upgrades, the dedicated worker additionally resolves the exact merged commit in the isolated runner. Only its validated POM is copied into a temporary Maven project, the pinned dependency-tree plugin exports all supported scopes, and a fresh complete advisory check covers the resolved inventory. Repository source, extensions and lifecycle hooks are not executed by confirmation.

The worker saves the manifest digest, merged commit, package count, advisory matches and runner image against the durable verification job. Fix progress identifies this as fresh Maven resolution. Confirmation requires that job to finish successfully, the selected dependency to remain present, and all removed advisories plus any advisory on the selected package to be absent. Imported scans cannot supply this evidence. Existing cancellation, three-attempt retry/backoff, tenant access and worker configuration checks apply. Rebuild the pinned runner image and restart the dedicated worker to enable this operation; no migration is needed.

Apply the database migration and restart the dedicated worker when upgrading. No deployment, new credentials, or billing changes are performed by repository enrollment.