AgentShield: Supply-Chain IOC Scanning for AI Agents

The supply chain is the first attack surface in any agentic workflow. Before your agent runs a single tool call, the npm packages it loaded, the MCP configs it trusts, and the hook scripts it executes may already be compromised. AgentShield is ECC’s automated IOC scanner for exactly this layer: it checks dependency manifests, lockfiles, installed package payloads, and AI-tool persistence paths against a catalog of active supply-chain indicators — raising findings before a compromised artifact can affect a live agent session.

Always run AgentShield before deploying ECC to a production agent environment. Supply-chain infections are silent by design; they do not announce themselves in normal output.

What AgentShield scans

AgentShield’s scanner (scan-supply-chain-iocs.js) targets four distinct surfaces:

npm & PyPI dependency trees

Checks package.json, package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock, pyproject.toml, poetry.lock, and requirements.txt for known compromised package versions. Also walks node_modules/ to inspect installed package payload files directly.

AI-tool persistence surfaces

Scans AI harness config directories — .claude/, .cursor/, .vscode/, .kiro/settings/ — for known payload filenames (router_runtime.js, setup.mjs, pgmonitor.py, gh-token-monitor.sh) and suspicious content patterns injected into hook or settings files.

System persistence paths

Checks macOS LaunchAgents (~/Library/LaunchAgents/), Linux systemd user units (~/.config/systemd/user/), local bin directories (~/.local/bin/), GitHub Actions workflow files (.github/workflows/), and known /tmp drop paths for IOC artifacts.

Unicode and content safety

Scans file content for known active IOC strings, including bidirectional text tricks, suspicious network endpoints, known C2 hostnames, and GitHub token monitor dead-man-switch artifacts.

What counts as an IOC

AgentShield maintains three IOC catalogs derived from real supply-chain incidents:

Known compromised package versions

A curated list of packages and exact versions confirmed as malicious. Examples from the catalog:

Package	Compromised versions
`node-ipc`	9.1.6, 9.2.3, 10.1.1–10.1.2, 11.0.0–11.1.0, 12.0.1
`@mistralai/mistralai`	2.2.2, 2.2.3, 2.2.4
`@opensearch-project/opensearch`	3.5.3, 3.6.2, 3.7.0, 3.8.0
`guardrails-ai`	0.10.1
`intercom-client`	7.0.4
`@tanstack/react-router`	1.169.5, 1.169.8
`@dirigible-ai/sdk`	0.6.2, 0.6.3

The full list covers over 150 packages across the npm and PyPI ecosystems. Any match raises a critical finding.

Critical text indicators

String patterns that indicate active supply-chain compromise when found in scanned files — including:

Known C2 hostnames: filev2.getsession.org, git-tanstack.com, sh.azurestaticprovider.net, api.masscan.cloud
AWS metadata service endpoint: 169.254.169.254 (IMDS exfiltration)
Known payload script names: tanstack_runner.js, router_init.js, opensearch_init.js, vite_setup.mjs
GitHub token monitor artifacts: gh-token-monitor, com.user.gh-token-monitor, IfYouRevokeThisTokenItWillWipeTheComputerOfTheOwner
Known GitHub Actions campaign markers: shai-hulud-workflow.yml, codeql_analysis.yml (as planted files, not the standard name)

Indicators found inside permissions.deny blocks in Claude settings files are excluded from findings — that is where you intentionally list dangerous patterns to block.

Known malicious file hashes

SHA-256 hashes of confirmed malicious tarballs and payloads (for example, specific node-ipc .cjs and .tgz artifacts). Any file whose hash matches raises a critical finding immediately, regardless of filename.

CLI usage

Run a scan

npx ecc security-ioc-scan

This runs scan-supply-chain-iocs.js against the repo root. Findings are printed to stderr; the process exits 1 if any IOC is found and 0 if the scan is clean.

# Scan a specific directory
npx ecc security-ioc-scan --root /path/to/project

# Also scan user-level persistence surfaces (Claude, VS Code, LaunchAgents, systemd, /tmp)
npx ecc security-ioc-scan --home

# Specify a custom home directory (useful in CI with a mounted home)
npx ecc security-ioc-scan --home --home-dir /home/runner

# Emit machine-readable JSON output
npx ecc security-ioc-scan --json

Interpreting output

A clean scan:

Supply-chain IOC scan passed for /home/user/myproject (47 files inspected)

A scan with findings:

CRITICAL: package-lock.json:12 @mistralai/mistralai@2.2.3
  Dependency manifest or lockfile references a known compromised package version
CRITICAL: .claude/settings.json:1 router_runtime.js
  Known Mini Shai-Hulud/TanStack payload or persistence filename is present

Each finding includes:

Severity — always critical for IOC matches
File path — relative to the scanned root
Line number — where in the file the indicator was detected
Indicator — the specific IOC that matched
Message — human-readable explanation of the finding

JSON output format

npx ecc security-ioc-scan --json

{
  "rootDir": "/home/user/myproject",
  "scannedFiles": 47,
  "findings": [
    {
      "severity": "critical",
      "filePath": "package-lock.json",
      "line": 12,
      "indicator": "@mistralai/mistralai@2.2.3",
      "message": "Dependency manifest or lockfile references a known compromised package version"
    }
  ]
}

CI integration

Add AgentShield to your GitHub Actions workflow to block compromised packages from reaching any deployed agent environment:

name: Security

on:
  push:
    branches: [main]
  pull_request:

jobs:
  supply-chain-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4

      - name: Set up Node.js
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 20

      - name: Run AgentShield IOC scan
        run: npx ecc security-ioc-scan --home --json

Pin all third-party GitHub Actions to commit SHAs, as shown above. This is ECC’s own supply-chain requirement for its CI workflows.

The workflow exits with a non-zero code if any IOC finding is present, blocking the PR or deployment automatically. Pass --json to capture structured output for downstream processing or SIEM ingestion.

How the scanner works internally

File discovery

The scanner walks the target directory, collecting files that match a known-relevant set: dependency manifests (package.json, lockfiles, requirements.txt), AI-tool config paths (.claude/settings.json, .vscode/tasks.json), persistence-surface filenames when found under special config directories, and known payload filenames when found under node_modules/.

Hash check

Each collected file is SHA-256 hashed and compared against the malicious file hash catalog. A match raises a critical finding immediately.

Payload filename check

Files whose base names appear in the payload filename set (router_runtime.js, tanstack_runner.js, pgmonitor.py, etc.) raise a critical finding — the presence of these filenames in the expected drop locations is itself an IOC.

Text IOC scan

File content is scanned for all critical text indicators. Matches inside permissions.deny blocks in Claude settings files are suppressed to avoid false positives from defensive denylists.

Dependency version check

For dependency manifests and lockfiles, each known compromised package@version pair is matched against both JSON-parsed structure and raw text (to cover YAML lockfiles and requirements files).

Installation

AgentShield is included in the --profile security and --modules security install options:

# Include at install time
npx ecc-universal install --profile security

# Add to an existing installation
npx ecc-universal install --modules security

The ecc-agentshield npm package is also available as a standalone scanner:

npx ecc-agentshield scan

The official AgentShield source is at github.com/affaan-m/agentshield. AgentShield code issues belong there; ECC usage-documentation issues belong in the affaan-m/ECC repository.

What AgentShield does not replace

AgentShield catches known IOCs. It does not replace:

Semantic code review — a novel, previously undocumented malicious package will not be in the IOC catalog.
Runtime sandboxing — IOC scanning is a pre-flight check, not a runtime containment layer.
Prompt injection defense — AgentShield scans files, not in-context model inputs.
Human approval gates — do not remove PreToolUse hook gates because the scan passed.

Run the scan as the first gate in your pipeline; keep all other layers in place behind it.

Getting Started

Core Concepts

Using ECC

Security

AgentShield: Supply-Chain IOC Scanning for AI Agents

What AgentShield scans

npm & PyPI dependency trees

AI-tool persistence surfaces

System persistence paths

Unicode and content safety

What counts as an IOC

Known compromised package versions

Critical text indicators

Known malicious file hashes

CLI usage

Run a scan

Interpreting output

JSON output format

CI integration

How the scanner works internally

Installation

What AgentShield does not replace

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Using ECC

Security

Documentation Index

​What AgentShield scans

npm & PyPI dependency trees

AI-tool persistence surfaces

System persistence paths

Unicode and content safety

​What counts as an IOC

​Known compromised package versions

​Critical text indicators

​Known malicious file hashes

​CLI usage

​Run a scan

​Interpreting output

​JSON output format

​CI integration

​How the scanner works internally

​Installation

​What AgentShield does not replace

Build docs developers (and LLMs) love

What AgentShield scans

What counts as an IOC

Known compromised package versions

Critical text indicators

Known malicious file hashes

CLI usage

Run a scan

Interpreting output

JSON output format

CI integration

How the scanner works internally

Installation

What AgentShield does not replace