Paketinstallationen von KI-Agenten über Proxy-Cooldowns leiten

Wie du Codex, Claude Code, npm und Python-Clients so konfigurierst, dass neue öffentliche Paketversionen erst nach einem Craftifact-Proxy-Cooldown installiert werden können.

Kurzpfad

Erstelle oder wähle npm- und Python-Proxy-Repositorys für öffentlichen Pakettraffic.
Hänge eine strikte Pull-Policy mit Cooldown-Fenster an.
Committe Package-Manager-Konfiguration, die Craftifact als Registry oder Paketindex setzt.
Ergänze AGENTS.md für Codex und importiere diese Datei aus CLAUDE.md für Claude Code.
Erzwinge die Grenze über Netzwerk- oder Sandbox-Regeln, damit der Agent Craftifact nicht umgehen kann.

Wogegen das schützt

Ein Cooldown-Gate hilft, wenn eine öffentliche Paketversion neu veröffentlicht, kompromittiert und dann erkannt oder entfernt wird, bevor der Cooldown abläuft. Im strikten Modus hält Craftifact zurückgehaltene Versionen aus den npm-Paketmetadaten und Python-Simple-API-Listings heraus und beantwortet direkte Paketdatei-Pulls über den Proxy mit einem Policy-Hold. Normale Installationen über diese Repositorys können die neue Version dadurch erst abrufen, wenn der Cooldown abgelaufen ist oder ein vertrauenswürdiger Nutzer sie per Fast-track freigibt. Dieselbe Pull-Policy kann außerdem Versionen mit bekannten Schwachstellen-Findings halten oder ablehnen, wenn Schwachstellenregeln konfiguriert sind und Analysedaten verfügbar sind.

Das ist keine Malware-Garantie. Es hilft nicht, wenn die kompromittierte Version schon älter als der Cooldown ist, bereits gecacht und freigegeben wurde, vor Aktivierung der Policy in einem Lockfile gepinnt war oder über einen direkten Netzwerkpfad außerhalb von Craftifact geladen wird. Es ersetzt außerdem nicht Schwachstellen-Triage, die Prüfung von Install-Skripten, Dependency-Änderungen und den Kommandos, die ein Agent vorschlägt.

Craftifact-Gate konfigurieren

Nutze eine strikte Pull-Policy für die npm- und Python-Proxy-Repositorys, die KI-Coding-Agenten verwenden. Ein Fenster von 72 Stunden ist ein praktikabler Startwert für öffentliche Abhängigkeiten, weil viele breite Supply-Chain-Vorfälle innerhalb von Stunden erkannt und bereinigt werden, während der Fast-Track-Workflow dringende Releases weiterhin bewusst freigeben kann.

pull_policies:
  default: agent-package-cooldown

  agent-package-cooldown:
    enforcement_mode: strict
    cooldown:
      minimum_release_age: 72h
      unknown_release_time: use_first_seen
    vulnerabilities:
      max_severity: high
      unknown_analysis: allow

repositories:
  - name: npm-public
    type: npm_proxy
    upstream_url: https://registry.npmjs.org
    pull_policy:
      policy: agent-package-cooldown

  - name: python-public
    type: python_proxy
    upstream_url: https://pypi.org
    pull_policy:
      policy: agent-package-cooldown

Nutze stattdessen unknown_release_time: hold, wenn das Repository Pakete ohne Veröffentlichungszeitpunkt blockieren soll, bis ein Mensch sie per Fast-track freigibt. Nutze vulnerabilities.unknown_analysis: hold nur, wenn Pakete ohne abgeschlossene Schwachstellenanalyse auf Analyse oder manuelle Prüfung warten sollen. Nutze die Fast-Track-Aktion für ein zurückgehaltenes Paket nur, nachdem du Paket, Release Notes, Maintainer-Kontext und den Grund geprüft hast, aus dem der Agent es benötigt.

Package-Manager-Konfiguration committen

Committe Registry- und Paketindex-URLs, aber halte Tokens in Umgebungsvariablen oder nutzerspezifischer Package-Manager-Konfiguration.

registry=https://packages.example.com/repository/npm/npm-public/
audit=false
fund=false
//packages.example.com/repository/npm/npm-public/:_authToken=${CRAFTIFACT_NPM_TOKEN}

Für Python kannst du die Paketindex-URL ohne Zugangsdaten committen, wenn das zu deinem Workflow passt:

[global]
index-url = https://packages.example.com/repository/python/python-public/simple/
disable-pip-version-check = true

Übergib die Zugangsdaten danach über die Agent- oder CI-Umgebung:

export PIP_INDEX_URL="https://__token__:${CRAFTIFACT_PYTHON_TOKEN}@packages.example.com/repository/python/python-public/simple/"

Setze ${CRAFTIFACT_PYTHON_TOKEN} nicht direkt in pip.conf; pip behandelt den Wert als Literal und expandiert die Umgebungsvariable nicht.

Für Poetry nutzt du dieselbe Python-Simple-API-URL und speicherst Zugangsdaten separat:

poetry source add --priority=primary craftifact \
  https://packages.example.com/repository/python/python-public/simple/
poetry config http-basic.craftifact __token__ "$CRAFTIFACT_PYTHON_TOKEN"

Nutze Robot-Tokens mit Leserechten auf den Proxy-Repositorys.

Erzeuge Lockfiles nach dem Wechsel der Paketquelle neu oder prüfe, dass bestehende Lockfiles keine direkten öffentlichen Registry-URLs pinnen:

rg "registry\.npmjs\.org|npmjs\.com|pypi\.org|pythonhosted\.org" package-lock.json npm-shrinkwrap.json pnpm-lock.yaml yarn.lock requirements*.txt poetry.lock uv.lock Pipfile.lock

Wenn diese Prüfung direkte öffentliche Registry- oder Paket-Host-URLs findet, erzeuge das Lockfile über Craftifact neu, bevor du dich auf das Cooldown-Gate verlässt.

Gemeinsame Agent-Anweisungen ergänzen

Codex liest AGENTS.md. Claude Code liest CLAUDE.md, deshalb kannst du eine gemeinsame Quelle nutzen, indem du AGENTS.md importierst. Diese Dateien steuern den Agenten, sind für sich allein aber keine Sicherheitsgrenze.

# AGENTS.md

## Dependency-Installationen

- Nutze den committeten Package Manager und das Lockfile.
- Nutze nur diese npm-Registry für Installationen: `https://packages.example.com/repository/npm/npm-public/`.
- Nutze nur diesen Python-Paketindex für Installationen: `https://packages.example.com/repository/python/python-public/simple/`.
- Führe keine npm-, pnpm-, Yarn-, npx-, pnpm-dlx-, yarn-dlx-, pip-, pipx-, Poetry-, uv- oder PDM-Kommandos aus, die Pakete direkt aus öffentlichen Registrys laden.
- Ändere `.npmrc`, `pip.conf`, Registry-URLs in Lockfiles oder Source-Einstellungen des Package Managers nicht, außer der Nutzer fordert diese Änderung ausdrücklich an.
- Wenn Craftifact einen Policy-Hold zurückgibt, stoppe und melde Paketname, Version und `X-Craftifact-Policy-Reason`.

# CLAUDE.md

@AGENTS.md

Halte Registry- und Index-URLs in der Anweisungsdatei synchron mit der committeten Package-Manager-Konfiguration.

Grenze in Codex erzwingen

Setze für Codex-Cloud-Umgebungen den Internetzugang des Agenten auf eine leere Allowlist plus den Host deiner Craftifact-Instanz. Für reine Installationsaufgaben reichen GET, HEAD und OPTIONS. Vermeide für diesen Workflow das Common-Dependencies-Preset, weil es öffentliche Paketregistrys enthält.

Setup-Skripte laufen weiterhin mit Internetzugang. Stelle deshalb sicher, dass auch Setup-Kommandos die committete .npmrc verwenden und nicht direkt von öffentlichem npm installieren. Stelle bei Python-Setup-Kommandos sicher, dass pip, uv, Poetry und verwandte Tools die Craftifact-Python-Simple-API-URL verwenden. Für lokale Codex-Sessions erzwingst du dieselbe Grenze außerhalb des Agenten über Workstation-Sandbox, Container, Firewall oder CI-Netzwerkpolicy.

Grenze in Claude Code erzwingen

Claude Code kann ausgehende Netzwerkdomains für sandboxed Shell-Kommandos erzwingen. In einer gemeinsamen Projektkonfiguration erlaubst du für Agent-Sessions, die npm- oder Python-Pakete über die Proxys installieren sollen, nur den Host der Craftifact-Instanz.

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "network": {
      "allowedDomains": ["packages.example.com"],
      "deniedDomains": [
        "registry.npmjs.org",
        "*.npmjs.org",
        "npmjs.com",
        "*.npmjs.com",
        "pypi.org",
        "*.pypi.org",
        "pythonhosted.org",
        "*.pythonhosted.org"
      ]
    }
  }
}

Wenn der Agent zusätzlich Netzwerkzugriff auf Source Control, Issue Tracker oder Dokumentation braucht, füge diese Domains bewusst hinzu und halte öffentliche npm- und Python-Paketdomains gesperrt.

Setup prüfen

Führe diese Checks in derselben Umgebung aus, die der Agent nutzt:

npm config get registry
npm view react version --registry https://packages.example.com/repository/npm/npm-public/
export PIP_INDEX_URL="https://__token__:${CRAFTIFACT_PYTHON_TOKEN}@packages.example.com/repository/python/python-public/simple/"
python -m pip index versions requests

Bitte den Agenten danach, vor einer Installation zu erklären, welche npm-Registry und welchen Python-Paketindex er verwenden darf. Für Codex kannst du ihn außerdem die aktiven AGENTS.md-Anweisungen auflisten lassen. Für Claude Code prüfst du in der Memory-Ansicht, dass der CLAUDE.md-Import geladen wurde.

Wenn ein Paket im Cooldown-Fenster liegt, gibt eine strikte Craftifact-Policy eine Hold-Antwort mit Policy-Decision-Headern zurück, statt still auf öffentliche Paketregistrys auszuweichen. Behandle das als funktionierende Kontrolle, nicht als Installationsfehler, den der Agent umgehen soll.