Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/workflows/dev-containers.yml
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,8 @@ jobs:
path: ${{ env.TGZ }}
tests-matrix:
name: Tests Matrix
runs-on: ubuntu-latest
# Ubuntu 26.04 (ubuntu-latest) breaks Compose builds (https://github.com/devcontainers/cli/issues/1320), the Docker-in-Docker Feature and Podman builds.
runs-on: ubuntu-24.04
timeout-minutes: 30
strategy:
fail-fast: false
Expand Down
3 changes: 2 additions & 1 deletion .github/workflows/test-docker-v29.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ permissions:
jobs:
test-docker-v29:
name: Docker v29.0.0 Compatibility
runs-on: ubuntu-latest
# Docker 29.0.0 has no package for Ubuntu 26.04 (ubuntu-latest).
runs-on: ubuntu-24.04
timeout-minutes: 20

steps:
Expand Down
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@

Notable changes.

## November 2026

### [0.91.0]
- Add `--docker-arg` option for global Docker CLI arguments. (https://github.com/devcontainers/cli/pull/1304)
- Report the lookup kinds and reasons for blocked OCI authentication lookups in diagnostics, and include the diagnostics in failed `up` results. (https://github.com/devcontainers/cli/pull/1361)

## October 2026

### [0.90.0]
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "@devcontainers/cli",
"description": "Dev Containers CLI",
"version": "0.90.0",
"version": "0.91.0",
"bin": {
"devcontainer": "devcontainer.js"
},
Expand Down
13 changes: 13 additions & 0 deletions src/spec-common/ociAuth.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,28 @@
* Licensed under the MIT License. See License.txt in the project root for license information.
*--------------------------------------------------------------------------------------------*/

export type OCIAuthLookupKind = 'image' | 'feature' | 'template';

// Why OCI auth hardening would block a token realm, checked in this order:
// - httpRealm: The realm does not use HTTPS.
// - differentPort: The realm is on the registry's hostname, but on a different port.
// - parentDomain: The realm is on a parent domain of the registry's hostname (e.g., registry.example.com and example.com).
// - differentHost: The realm is on any other host.
export type OCIAuthLookupBlockedReason = 'httpRealm' | 'differentPort' | 'parentDomain' | 'differentHost';

export interface OCIAuthDiagnostics {
authLookupWouldBeBlocked: boolean;
authLookupBlockedKinds: OCIAuthLookupKind[];
authLookupBlockedReasons: OCIAuthLookupBlockedReason[];
registryRedirectWouldPreventCredentialForwarding: boolean;
authServerRedirect: boolean;
}

export function createOCIAuthDiagnostics(): OCIAuthDiagnostics {
return {
authLookupWouldBeBlocked: false,
authLookupBlockedKinds: [],
authLookupBlockedReasons: [],
registryRedirectWouldPreventCredentialForwarding: false,
authServerRedirect: false,
};
Expand Down
3 changes: 2 additions & 1 deletion src/spec-configuration/containerCollectionsOCI.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { Log, LogLevel } from '../spec-utils/log';
import { isLocalFile, mkdirpLocal, readLocalFile, writeLocalFile } from '../spec-utils/pfs';
import { requestEnsureAuthenticated } from './httpOCIRegistry';
import { GoARCH, GoOS, PlatformInfo } from '../spec-common/commonUtils';
import { OCIAuthDiagnostics } from '../spec-common/ociAuth';
import { OCIAuthDiagnostics, OCIAuthLookupKind } from '../spec-common/ociAuth';

export const DEVCONTAINER_MANIFEST_MEDIATYPE = 'application/vnd.devcontainers';
export const DEVCONTAINER_TAR_LAYER_MEDIATYPE = 'application/vnd.devcontainers.layer.v1+tar';
Expand All @@ -22,6 +22,7 @@ export interface CommonParams {
allowedCrossOriginAuthHosts?: string[];
ociAuthHardening?: boolean;
ociAuthDiagnostics: OCIAuthDiagnostics;
ociAuthLookupKind: OCIAuthLookupKind;
}

// Represents the unique OCI identifier for a Feature or Template.
Expand Down
1 change: 1 addition & 0 deletions src/spec-configuration/containerFeaturesConfiguration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,7 @@ export interface ContainerFeatureInternalParams {
allowedCrossOriginAuthHosts?: string[];
ociAuthHardening?: boolean;
ociAuthDiagnostics: OCIAuthDiagnostics;
ociAuthLookupKind: 'feature';
}

// TODO: Move to node layer.
Expand Down
49 changes: 45 additions & 4 deletions src/spec-configuration/httpOCIRegistry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import { requestResolveHeaders, requestResolveHeadersNoRedirects } from '../spec
import { LogLevel } from '../spec-utils/log';
import { isLocalFile, readLocalFile } from '../spec-utils/pfs';
import { CommonParams, OCICollectionRef, OCIRef } from './containerCollectionsOCI';
import { OCIAuthDiagnostics } from '../spec-common/ociAuth';
import { OCIAuthLookupBlockedReason } from '../spec-common/ociAuth';

export type HEADERS = { 'authorization'?: string; 'user-agent'?: string; 'content-type'?: string; 'Accept'?: string; 'content-length'?: string };

Expand Down Expand Up @@ -126,17 +126,58 @@ export function isAllowedTokenServiceRealm(realm: string, registryUrl: string, c
}
}

function recordOCIAuthDiagnostic(params: CommonParams, key: keyof OCIAuthDiagnostics, message: string) {
function recordOCIAuthDiagnostic(params: CommonParams, key: 'registryRedirectWouldPreventCredentialForwarding' | 'authServerRedirect', message: string) {
if (!params.ociAuthDiagnostics[key]) {
params.ociAuthDiagnostics[key] = true;
params.output.write(`[httpOci] OCI auth diagnostics: ${message}`, LogLevel.Info);
}
}

export function getAuthLookupBlockedReason(registryUrl: URL, realmUrl: URL): OCIAuthLookupBlockedReason {
if (realmUrl.protocol !== 'https:') {
return 'httpRealm';
}
const registryHostname = registryUrl.hostname.toLowerCase();
const realmHostname = realmUrl.hostname.toLowerCase();
if (realmHostname === registryHostname) {
return 'differentPort';
}
if (registryHostname.endsWith(`.${realmHostname}`)) {
return 'parentDomain';
}
return 'differentHost';
}

function addSortedUnique<T extends string>(values: T[], value: T) {
if (values.includes(value)) {
return false;
}
values.push(value);
values.sort();
return true;
}

function recordAuthLookupWouldBeBlocked(params: CommonParams, registryUrl: URL, realmUrl: URL) {
const diagnostics = params.ociAuthDiagnostics;
const kind = params.ociAuthLookupKind;
const reason = getAuthLookupBlockedReason(registryUrl, realmUrl);
diagnostics.authLookupWouldBeBlocked = true;
const newKind = addSortedUnique(diagnostics.authLookupBlockedKinds, kind);
const newReason = addSortedUnique(diagnostics.authLookupBlockedReasons, reason);
if (newKind || newReason) {
params.output.write(`[httpOci] OCI auth diagnostics: Authentication lookup for ${kind} from registry '${registryUrl.host}' to realm origin '${realmUrl.origin}' would be blocked by OCI auth hardening (${reason}).`, LogLevel.Info);
}
}

function withOCIAuthDiagnostics<T extends object>(params: CommonParams, result: T) {
const diagnostics = params.ociAuthDiagnostics;
return {
...result,
ociAuthDiagnostics: { ...params.ociAuthDiagnostics },
ociAuthDiagnostics: {
...diagnostics,
authLookupBlockedKinds: [...diagnostics.authLookupBlockedKinds],
authLookupBlockedReasons: [...diagnostics.authLookupBlockedReasons],
},
};
}

Expand Down Expand Up @@ -237,7 +278,7 @@ export async function requestEnsureAuthenticated(params: CommonParams, httpOptio
const crossOriginAuthHosts = parseCrossOriginAuthHosts([...builtInCrossOriginAuthHosts, ...(params.allowedCrossOriginAuthHosts || [])]);
const authLookupWouldBeBlocked = !isAllowedTokenServiceRealmForPolicy(realmUrl, registryUrl, crossOriginAuthHosts);
if (authLookupWouldBeBlocked) {
recordOCIAuthDiagnostic(params, 'authLookupWouldBeBlocked', `Authentication lookup from registry '${registryUrl.host}' to realm origin '${realmUrl.origin}' would be blocked by OCI auth hardening.`);
recordAuthLookupWouldBeBlocked(params, registryUrl, realmUrl);
if (params.ociAuthHardening) {
delete cachedAuthHeader[ociRef.registry];
const allowHint = realmUrl.protocol === 'https:'
Expand Down
2 changes: 1 addition & 1 deletion src/spec-node/containerFeatures.ts
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ export async function getExtendImageBuildInfo(params: DockerResolverParameters,

const cacheFolder = await getCacheFolder(params.common.cliHost);
const { noLockfile, frozenLockfile } = params;
const featuresConfig = await generateFeaturesConfig({ ...params.common, platform, cacheFolder, noLockfile, frozenLockfile }, dstFolder, config.config, additionalFeatures);
const featuresConfig = await generateFeaturesConfig({ ...params.common, platform, cacheFolder, noLockfile, frozenLockfile, ociAuthLookupKind: 'feature' }, dstFolder, config.config, additionalFeatures);
if (!featuresConfig) {
if (canAddLabelsToContainer && !imageBuildInfo.dockerfile) {
return {
Expand Down
5 changes: 3 additions & 2 deletions src/spec-node/devContainers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import * as crypto from 'crypto';
import * as os from 'os';

import { mapNodeOSToGOOS, mapNodeArchitectureToGOARCH } from '../spec-configuration/containerCollectionsOCI';
import { createOCIAuthDiagnostics } from '../spec-common/ociAuth';
import { createOCIAuthDiagnostics, OCIAuthDiagnostics } from '../spec-common/ociAuth';
import { DockerResolverParameters, DevContainerAuthority, UpdateRemoteUserUIDDefault, BindMountConsistency, getCacheFolder, GPUAvailability } from './utils';
import { createNullLifecycleHook, finishBackgroundTasks, ResolverParameters, UserEnvProbe } from '../spec-common/injectHeadless';
import { GoARCH, GoOS, getCLIHost, loadNativeModule } from '../spec-common/commonUtils';
Expand Down Expand Up @@ -78,6 +78,7 @@ export interface ProvisionOptions {
includeMergedConfig?: boolean;
allowedCrossOriginAuthHosts?: string[];
ociAuthHardening?: boolean;
ociAuthDiagnostics?: OCIAuthDiagnostics;
}

export async function launch(options: ProvisionOptions, providedIdLabels: string[] | undefined, disposables: (() => Promise<unknown> | undefined)[]) {
Expand Down Expand Up @@ -169,7 +170,7 @@ export async function createDockerParams(options: ProvisionOptions, disposables:
omitSyntaxDirective: options.omitSyntaxDirective,
allowedCrossOriginAuthHosts: options.allowedCrossOriginAuthHosts,
ociAuthHardening: options.ociAuthHardening,
ociAuthDiagnostics: createOCIAuthDiagnostics(),
ociAuthDiagnostics: options.ociAuthDiagnostics || createOCIAuthDiagnostics(),
};

const dockerPath = options.dockerPath || 'docker';
Expand Down
5 changes: 4 additions & 1 deletion src/spec-node/devContainersSpecCLI.ts
Original file line number Diff line number Diff line change
Expand Up @@ -361,8 +361,9 @@ async function doProvision(options: ProvisionOptions, providedIdLabels: string[]
const dispose = async () => {
await Promise.all(disposables.map(d => d()));
};
const ociAuthDiagnostics = options.ociAuthDiagnostics || createOCIAuthDiagnostics();
try {
const result = await launch(options, providedIdLabels, disposables);
const result = await launch({ ...options, ociAuthDiagnostics }, providedIdLabels, disposables);
return {
outcome: 'success' as 'success',
dispose,
Expand All @@ -385,6 +386,7 @@ async function doProvision(options: ProvisionOptions, providedIdLabels: string[]
disallowedFeatureId: err.data.disallowedFeatureId,
didStopContainer: err.data.didStopContainer,
learnMoreUrl: err.data.learnMoreUrl,
ociAuthDiagnostics,
dispose,
};
}
Expand Down Expand Up @@ -1284,6 +1286,7 @@ async function outdated({
allowedCrossOriginAuthHosts,
ociAuthHardening,
ociAuthDiagnostics: createOCIAuthDiagnostics(),
ociAuthLookupKind: 'feature' as 'feature',
};

const outdated = await loadVersionInfo(params, configs.config.config);
Expand Down
1 change: 1 addition & 0 deletions src/spec-node/featureUtils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,5 +21,6 @@ export async function readFeaturesConfig(params: DockerCLIParameters, pkg: Packa
allowedCrossOriginAuthHosts: params.allowedCrossOriginAuthHosts,
ociAuthHardening: params.ociAuthHardening,
ociAuthDiagnostics: params.ociAuthDiagnostics,
ociAuthLookupKind: 'feature',
}, featuresTmpFolder, config, additionalFeatures);
}
2 changes: 1 addition & 1 deletion src/spec-node/featuresCLI/info.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ async function featuresInfo({
terminalDimensions: undefined,
}, pkg, new Date(), disposables, true);

const params = { output, env: process.env, outputFormat, allowedCrossOriginAuthHosts, ociAuthHardening, ociAuthDiagnostics: createOCIAuthDiagnostics() };
const params = { output, env: process.env, outputFormat, allowedCrossOriginAuthHosts, ociAuthHardening, ociAuthDiagnostics: createOCIAuthDiagnostics(), ociAuthLookupKind: 'feature' as 'feature' };

const jsonOutput: InfoJsonOutput = {};

Expand Down
2 changes: 1 addition & 1 deletion src/spec-node/featuresCLI/publish.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ async function featuresPublish({
terminalDimensions: undefined,
}, pkg, new Date(), disposables);

const params = { output, env: process.env, allowedCrossOriginAuthHosts, ociAuthHardening, ociAuthDiagnostics: createOCIAuthDiagnostics() };
const params = { output, env: process.env, allowedCrossOriginAuthHosts, ociAuthHardening, ociAuthDiagnostics: createOCIAuthDiagnostics(), ociAuthLookupKind: 'feature' as 'feature' };

// Package features
const outputDir = path.join(os.tmpdir(), `/features-output-${Date.now()}`);
Expand Down
1 change: 1 addition & 0 deletions src/spec-node/featuresCLI/resolveDependencies.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ async function featuresResolveDependencies({
allowedCrossOriginAuthHosts,
ociAuthHardening,
ociAuthDiagnostics: createOCIAuthDiagnostics(),
ociAuthLookupKind: 'feature' as 'feature',
};

const cwd = workspaceFolder || process.cwd();
Expand Down
2 changes: 1 addition & 1 deletion src/spec-node/templatesCLI/apply.ts
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ async function templateApply({
omitPaths,
};

const files = await fetchTemplate({ output, env: process.env, allowedCrossOriginAuthHosts, ociAuthHardening, ociAuthDiagnostics: createOCIAuthDiagnostics() }, selectedTemplate, workspaceFolder, userProvidedTmpDir);
const files = await fetchTemplate({ output, env: process.env, allowedCrossOriginAuthHosts, ociAuthHardening, ociAuthDiagnostics: createOCIAuthDiagnostics(), ociAuthLookupKind: 'template' }, selectedTemplate, workspaceFolder, userProvidedTmpDir);
if (!files) {
output.write(`Failed to fetch template '${id}'.`, LogLevel.Error);
process.exit(1);
Expand Down
2 changes: 1 addition & 1 deletion src/spec-node/templatesCLI/metadata.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ async function templateMetadata({
terminalDimensions: undefined,
}, pkg, new Date(), disposables);

const params = { output, env: process.env, allowedCrossOriginAuthHosts, ociAuthHardening, ociAuthDiagnostics: createOCIAuthDiagnostics() };
const params = { output, env: process.env, allowedCrossOriginAuthHosts, ociAuthHardening, ociAuthDiagnostics: createOCIAuthDiagnostics(), ociAuthLookupKind: 'template' as 'template' };
output.write(`Fetching metadata for ${templateId}`, LogLevel.Trace);

const templateRef = getRef(output, templateId);
Expand Down
2 changes: 1 addition & 1 deletion src/spec-node/templatesCLI/publish.ts
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ async function templatesPublish({
terminalDimensions: undefined,
}, pkg, new Date(), disposables);

const params = { output, env: process.env, allowedCrossOriginAuthHosts, ociAuthHardening, ociAuthDiagnostics: createOCIAuthDiagnostics() };
const params = { output, env: process.env, allowedCrossOriginAuthHosts, ociAuthHardening, ociAuthDiagnostics: createOCIAuthDiagnostics(), ociAuthLookupKind: 'template' as 'template' };

// Package templates
const outputDir = path.join(os.tmpdir(), `/templates-output-${Date.now()}`);
Expand Down
1 change: 1 addition & 0 deletions src/spec-node/upgradeCommand.ts
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ async function featuresUpgrade({
allowedCrossOriginAuthHosts,
ociAuthHardening,
ociAuthDiagnostics,
ociAuthLookupKind: 'feature' as 'feature',
};

if (feature && targetVersion) {
Expand Down
2 changes: 1 addition & 1 deletion src/spec-node/utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -332,7 +332,7 @@ function logErrorStdoutStderr(err: any, output: Log) {

export async function inspectImageInRegistry(output: Log, platformInfo: PlatformInfo, name: string, allowedCrossOriginAuthHosts?: string[], ociAuthHardening?: boolean, ociAuthDiagnostics: OCIAuthDiagnostics = createOCIAuthDiagnostics()): Promise<ImageDetails> {
const resourceAndVersion = qualifyImageName(name);
const params = { output, env: process.env, allowedCrossOriginAuthHosts, ociAuthHardening, ociAuthDiagnostics };
const params = { output, env: process.env, allowedCrossOriginAuthHosts, ociAuthHardening, ociAuthDiagnostics, ociAuthLookupKind: 'image' as 'image' };
const ref = getRef(output, resourceAndVersion);
if (!ref) {
throw new Error(`Could not parse image name '${name}'`);
Expand Down
2 changes: 2 additions & 0 deletions src/test/cli.up.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import * as assert from 'assert';
import * as path from 'path';
import * as fs from 'fs';
import * as os from 'os';
import { createOCIAuthDiagnostics } from '../spec-common/ociAuth';
import { devContainerDown, devContainerUp, shellExec, UpResult } from './testUtils';

const pkg = require('../../package.json');
Expand Down Expand Up @@ -65,6 +66,7 @@ describe('Dev Containers CLI', function () {
const res = JSON.parse(error.stdout);
assert.equal(res.outcome, 'error');
assert.match(res.message, /Dev container config \(.*\) not found./);
assert.deepEqual(res.ociAuthDiagnostics, createOCIAuthDiagnostics());
}
assert.equal(success, false, 'expect non-successful call');
});
Expand Down
Loading
Loading