feat(security): gate AI-agent artifact installation

CHANGELOG.md

@@ -4,9 +4,20 @@
 
 ### Security
 
+- Added the independently deployable Agent Artifact Admission Controller for authenticated, loopback-only, fail-closed pre-execution package-install admission. Reviewed policy binds workspace manifests and exact artifact ecosystem/name/version/HTTPS registry/owner/SHA-256 evidence, structured argv, minimized append-before-response audit evidence, and deny-all defaults without taking over hostile-workload execution from the quarantine runtime.
+- Hardened package-manager command admission so approved artifacts cannot be reinterpreted by a different package-manager ecosystem or widened through alternate package sources, destinations, executable install hooks, parser boundaries, persistent trust mutation, integrity-verification disablement, opaque runtime configuration, or undeclared resolver output: standalone `--` option terminators are rejected so required safety flags cannot move behind a downstream CLI parsing boundary; npm-family commands bind to npm artifacts, pip/uv pip to PyPI, Cargo to Cargo, and Docker/Podman to OCI; npm caller-selected `--userconfig`/`--globalconfig` files and `--ca`/`--cafile`/`--strict-ssl` TLS trust overrides, pip source/root short and long forms, uv index/environment selectors, Cargo registry/Git/path/config/root selectors, npm workspace controls, pnpm `--dir`/`-C` working-directory, filter/recursive/workspace-root selectors, `--config.<key>=<value>` runtime overrides, and pnpmfile hooks not suppressed by `--ignore-scripts`, Yarn Classic `-W`/`--ignore-workspace-root-check`, Bun `--cwd`/`--filter`/`-F` workspace selectors, caller-supplied `--config`, `--trust` persistent `trustedDependencies` expansion, and `--no-verify` registry-integrity bypass, and contradictory lifecycle-script Boolean flags fail closed with stable reason codes. pnpm requests still require both `--ignore-scripts` and `--ignore-pnpmfile` before resolver authority is considered; pip, pip3, and `uv pip install` require exact `--no-deps` so the resolver cannot add artifacts absent from the reviewed intent.
+- Fail closed when a pip/pip3 install request includes `--no-require-hashes`: Wardnet's approved PyPI path requires hash-checking mode and does not accept a contradictory installer option that disables automatic hash enforcement alongside the positive requirement. This parser-boundary denial is separate from downstream proof that retrieved bytes match the reviewed artifact digest.
+- Fail closed on direct `npm install`, `pnpm add/install`, `yarn add`, and `bun add/install` even when the direct package coordinate and execution-hardening flags match policy, because the v0.1 intent carries only reviewed direct artifacts and cannot prove the transitive dependency closure those commands may resolve. `--ignore-scripts` is execution hardening, not dependency identity. A future npm-family allow path requires a reviewed immutable lockfile/material-set contract plus an executor command that is proven to consume that exact closure without rewriting it; until then resolver-selected transitive artifacts have no Wardnet admission authority.
+- Bound registry/index package source identity to the reviewed artifact coordinate: npm/pnpm/Yarn/Bun direct package operands must encode the exact reviewed `<name>@<version>`, and pip/pip3/`uv pip install` operands must encode the exact reviewed `<name>==<version>`. npm aliases, tarball/git/folder package specs and pip direct URL/VCS/local-source requirements cannot inherit approval from a different reviewed registry/index coordinate; unsafe policy drift fails closed during service configuration as well as request admission.
+- Bound Cargo install mutation authority to reviewed policy: caller-supplied `-f` / `--force` overwrite capability and `--no-track` metadata/concurrent-install bypass now fail closed as `artifact_not_approved` because the approved artifact coordinate does not authorize replacing existing binaries or disabling Cargo's install tracking/collision protection.
+- Bound PyPI approval to the reviewed artifact/build identity rather than caller-selected installer resolution or build variants: pip `--platform`, `--python-version`, `--implementation`, `--abi`, binary/source selectors, build-isolation controls, and `-C` / `--config-settings`, together with the corresponding `uv pip install` target-platform/binary/source/build/backend controls, fail closed as `artifact_not_approved` until policy can bind the selected distribution/build identity explicitly.
+- Bound OCI pull approval to the reviewed artifact identity rather than caller-selected client variants: Docker/Podman `--platform` and Podman-equivalent `--arch`, `--os`, and `--variant` selectors fail closed as `artifact_not_approved` until a versioned policy schema can authorize the selected platform-specific manifest identity or equivalent provenance.
+- Bound OCI pull cardinality to the exact reviewed artifact set: Docker/Podman `-a` / `--all-tags`, true Boolean assignments, and bundled Boolean shorthand semantics fail closed as `artifact_not_approved` whenever they enable repository-wide mutable tag expansion. This includes `-aq` / `-qa` and assigned bundles such as `-aq=false`, where the preceding `-a` remains enabled; quiet-only shorthand and a final explicitly false all-tags shorthand such as `-qa=false` remain admissible.
+- Bound Podman registry transport, authentication, and image-decryption authority to reviewed policy: false forms of `--tls-verify`, caller-selected `--cert-dir` / `--authfile`, inline `--creds`, and `--decryption-key` key/passphrase material fail closed as `alternate_trust_root`, while explicit TLS verification remains compatible with the approved registry identity. Registry credentials and image-decryption secrets remain separately governed downstream deployment/secret authorities rather than untrusted install argv.
 - Removed the distributable Kubernetes administrator `Secret` and historical placeholder credential. Production deployments must provision `waf-ids-ai-soc-admin` / `ADMIN_TOKEN` through the external secret-management control plane; the workload's `secretKeyRef` is explicitly non-optional.
 - Added a structural regression contract that rejects shipped administrator Secret objects, placeholder credentials, decoy workloads, init-container false positives, and optional administrator Secret references.
 
 ### Operations
 
-- Documented administrator credential provisioning, rotation, rollout verification, rollback, evidence handling, and the boundary with the separate runtime-authentication fail-closed work tracked in issue #78.
+- Documented Agent Artifact Admission deployment, incident response, immutable policy rollout, audit durability, external provenance authority, package-manager ecosystem binding, package-manager trust/destination/parser controls, package source-coordinate binding, npm-family transitive dependency-closure denial, Cargo overwrite/tracking authority, PyPI artifact/build-variant and dependency-cardinality controls, exact-set OCI pull cardinality, OCI platform-variant and registry transport/authentication/decryption authority, Bun persistent trust and integrity-verification semantics, and current primary-source traceability.
+- Documented administrator credential provisioning, rotation, rollout verification, rollback, evidence handling, and the boundary with the separate runtime-authentication fail-closed work tracked in issue #78.

Cargo.toml

@@ -6,7 +6,7 @@ description = "Rust-first WAF/IDS/AI SOC gateway with DNSBL and commercial readi
 license = "MIT"
 
 [workspace]
-members = [".", "crates/waf-ids-core"]
+members = [".", "crates/waf-ids-core", "crates/agent-artifact-admission"]
 resolver = "3"
 
 [dependencies]
@@ -23,3 +23,4 @@ tower = { version = "0.5", features = ["util"] }
 # Property-based testing (MIT OR Apache-2.0); mirrors the cargo-fuzz target for
 # parse_admin_tokens so its invariants stay green in primary CI.
 proptest = "1"
+wardnet-agent-artifact-admission = { path = "crates/agent-artifact-admission" }

crates/agent-artifact-admission/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "wardnet-agent-artifact-admission"
+version = "0.1.0"
+edition = "2024"
+description = "Fail-closed package-install admission policy for AI coding agents"
+license = "MIT"
+
+[dependencies]
+axum = "0.8"
+ring = "0.17"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["macros", "net", "rt-multi-thread", "signal"] }
+url = "2"
+
+[dev-dependencies]
+tower = { version = "0.5", features = ["util"] }

crates/agent-artifact-admission/src/admission.rs

@@ -0,0 +1,283 @@
+use serde::{Deserialize, Serialize};
+
+/// Immutable admission policy loaded through reviewed configuration.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(deny_unknown_fields)]
+pub struct AdmissionPolicy {
+    /// Stable policy identifier surfaced in responses and audit records.
+    pub policy_id: String,
+    /// Immutable policy revision identifier.
+    pub policy_revision: String,
+    /// Executables that may be considered for admission.
+    #[serde(default)]
+    pub allowed_executables: Vec<String>,
+    /// Reviewed workspace manifest digests.
+    #[serde(default)]
+    pub approved_manifests: Vec<ApprovedManifest>,
+    /// Exact approved install artifacts.
+    #[serde(default)]
+    pub approved_artifacts: Vec<ApprovedArtifact>,
+}
+
+impl AdmissionPolicy {
+    /// Test helper that proves the evaluator blocks when nothing is approved.
+    pub fn deny_all_for_test() -> Self {
+        Self {
+            policy_id: "deny-all".to_string(),
+            policy_revision: "test".to_string(),
+            allowed_executables: Vec::new(),
+            approved_manifests: Vec::new(),
+            approved_artifacts: Vec::new(),
+        }
+    }
+}
+
+/// Reviewed manifest identity allowed by policy.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ApprovedManifest {
+    /// Workspace identifier the reviewed manifest belongs to.
+    pub workspace_id: String,
+    /// Exact SHA-256 digest of the reviewed manifest.
+    pub sha256: String,
+}
+
+/// Exact package artifact allowed by policy.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ApprovedArtifact {
+    /// Package ecosystem, such as `npm` or `cargo`.
+    pub ecosystem: String,
+    /// Exact package name.
+    pub name: String,
+    /// Exact package version.
+    pub version: String,
+    /// Normalized registry URL.
+    pub registry_url: String,
+    /// Reviewed package owner or publisher label.
+    pub owner: String,
+    /// Exact artifact SHA-256 digest.
+    pub sha256: String,
+    /// Exact argv token that names the artifact to install.
+    pub artifact_argument: String,
+}
+
+/// One requested artifact inside an install intent.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ArtifactCoordinate {
+    /// Package ecosystem, such as `npm` or `cargo`.
+    pub ecosystem: String,
+    /// Exact package name.
+    pub name: String,
+    /// Exact package version.
+    pub version: String,
+    /// Normalized registry URL.
+    pub registry_url: String,
+    /// Claimed package owner or publisher label.
+    pub owner: String,
+    /// Exact artifact SHA-256 digest.
+    pub sha256: String,
+    /// Exact argv token that names the artifact to install.
+    pub artifact_argument: String,
+}
+
+/// Provenance of the instruction that requested the install.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct InstructionSource {
+    /// Untrusted source category.
+    pub kind: InstructionSourceKind,
+    /// Canonical source URI when available.
+    pub uri: Option<String>,
+    /// SHA-256 digest of the retrieved source content.
+    pub content_sha256: Option<String>,
+}
+
+/// Untrusted instruction source kinds.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum InstructionSourceKind {
+    /// `llms.txt` retrieved from a remote origin.
+    LlmsTxt,
+    /// `llms-full.txt` retrieved from a remote origin.
+    LlmsFullTxt,
+    /// Arbitrary web page content.
+    WebPage,
+    /// Issue or PR comment content.
+    IssueComment,
+    /// Local reviewed manifest or operator-entered content.
+    ReviewedConfig,
+}
+
+/// Structured install request evaluated before any executor runs it.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct InstallIntent {
+    /// Stable request identifier supplied by the caller.
+    pub request_id: String,
+    /// Identity of the requesting agent or broker.
+    pub actor_id: String,
+    /// Workspace or repository identifier.
+    pub workspace_id: String,
+    /// Structured operation, limited to install in this slice.
+    pub operation: String,
+    /// Tokenized command vector; shell strings are forbidden upstream.
+    pub argv: Vec<String>,
+    /// Exact reviewed dependency-manifest digest for the workspace.
+    pub manifest_sha256: String,
+    /// Instruction provenance.
+    pub source: InstructionSource,
+    /// Exact install artifacts represented in `argv`.
+    pub artifacts: Vec<ArtifactCoordinate>,
+}
+
+impl InstallIntent {
+    /// Test helper representing an untrusted `llms.txt` package suggestion.
+    pub fn unowned_llms_package_for_test() -> Self {
+        Self {
+            request_id: "req-test-0001".to_string(),
+            actor_id: "agent:codex:test".to_string(),
+            workspace_id: "ContextualWisdomLab/wardnet".to_string(),
+            operation: "install".to_string(),
+            argv: vec![
+                "npm".to_string(),
+                "install".to_string(),
+                "@unowned/example@1.2.3".to_string(),
+                "--ignore-scripts".to_string(),
+            ],
+            manifest_sha256: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+                .to_string(),
+            source: InstructionSource {
+                kind: InstructionSourceKind::LlmsTxt,
+                uri: Some("https://example.invalid/llms.txt".to_string()),
+                content_sha256: Some(
+                    "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb".to_string(),
+                ),
+            },
+            artifacts: vec![ArtifactCoordinate {
+                ecosystem: "npm".to_string(),
+                name: "@unowned/example".to_string(),
+                version: "1.2.3".to_string(),
+                registry_url: "https://registry.npmjs.org".to_string(),
+                owner: "Unowned".to_string(),
+                sha256: "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+                    .to_string(),
+                artifact_argument: "@unowned/example@1.2.3".to_string(),
+            }],
+        }
+    }
+}
+
+/// Deterministic allow/block result returned to the caller.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct AdmissionDecision {
+    /// Original caller request identifier or a content-addressed malformed surrogate.
+    pub request_id: String,
+    /// Final policy decision.
+    pub decision: DecisionKind,
+    /// Stable machine-readable block reasons.
+    pub reason_codes: Vec<ReasonCode>,
+    /// Stable policy identifier.
+    pub policy_id: String,
+    /// Stable policy revision.
+    pub policy_revision: String,
+    /// Normalized source URI when present.
+    pub normalized_source_uri: Option<String>,
+    /// SHA-256 of the structured command vector or malformed request body.
+    pub command_sha256: String,
+    /// Number of artifacts the caller asked to install.
+    pub artifact_count: usize,
+}
+
+/// Admission outcome.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DecisionKind {
+    /// The command exactly matches policy.
+    Allow,
+    /// The command must not be executed.
+    Block,
+}
+
+impl DecisionKind {
+    /// Stable string form used by tests and callers that do not deserialize.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Allow => "allow",
+            Self::Block => "block",
+        }
+    }
+}
+
+/// Stable machine-readable block reason.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ReasonCode {
+    /// The request body could not be parsed as the strict install-intent schema.
+    MalformedRequest,
+    /// The authenticated request body exceeded the configured materialization limit.
+    RequestBodyTooLarge,
+    /// A bounded identifier, argument vector, source field, or count was invalid.
+    InvalidRequest,
+    /// The structured operation was not the supported install operation.
+    InvalidOperation,
+    /// The reviewed workspace manifest digest was malformed.
+    InvalidManifestDigest,
+    /// One or more artifact coordinates were malformed or unpinned.
+    InvalidArtifact,
+    /// Duplicate artifact identities or artifact argument tokens were supplied.
+    DuplicateArtifact,
+    /// No exact approved artifact matched the requested install.
+    ArtifactNotApproved,
+    /// No reviewed manifest matched the workspace digest.
+    ManifestNotApproved,
+    /// The executable is not on the explicit allowlist.
+    ExecutableNotAllowed,
+    /// The request omitted an executable.
+    MissingExecutable,
+    /// The request omitted a required remote source URI.
+    MissingSourceUri,
+    /// The request omitted a required source content digest.
+    MissingSourceDigest,
+    /// The request used an insecure or malformed source URI.
+    InvalidSourceUri,
+    /// The command path is forbidden even if otherwise allowlisted.
+    ForbiddenCommand,
+    /// The command attempted to introduce an alternate package trust root.
+    AlternateTrustRoot,
+    /// The command attempted to install outside the executor-selected workspace root.
+    AlternateInstallRoot,
+    /// The package manager invocation omitted a mandatory hardening flag.
+    MissingSafetyFlag,
+    /// Durable audit evidence could not be persisted before returning a decision.
+    AuditUnavailable,
+}
+
+impl ReasonCode {
+    /// Stable string form used by tests and audit sinks.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::MalformedRequest => "malformed_request",
+            Self::RequestBodyTooLarge => "request_body_too_large",
+            Self::InvalidRequest => "invalid_request",
+            Self::InvalidOperation => "invalid_operation",
+            Self::InvalidManifestDigest => "invalid_manifest_digest",
+            Self::InvalidArtifact => "invalid_artifact",
+            Self::DuplicateArtifact => "duplicate_artifact",
+            Self::ArtifactNotApproved => "artifact_not_approved",
+            Self::ManifestNotApproved => "manifest_not_approved",
+            Self::ExecutableNotAllowed => "executable_not_allowed",
+            Self::MissingExecutable => "missing_executable",
+            Self::MissingSourceUri => "missing_source_uri",
+            Self::MissingSourceDigest => "missing_source_digest",
+            Self::InvalidSourceUri => "invalid_source_uri",
+            Self::ForbiddenCommand => "forbidden_command",
+            Self::AlternateTrustRoot => "alternate_trust_root",
+            Self::AlternateInstallRoot => "alternate_install_root",
+            Self::MissingSafetyFlag => "missing_safety_flag",
+            Self::AuditUnavailable => "audit_unavailable",
+        }
+    }
+}