Codex

Integrate sus with Codex CLI using AGENTS.md instructions and Rules

Unlike other AI coding tools, Codex CLI does not have a hooks system. Instead, it offers two mechanisms for integrating sus:

1. AGENTS.md - Instruction files that Codex reads before every task
2. Rules (experimental) - A policy system that can block or prompt for commands

Both approaches ensure that package installations go through sus for security scanning.

Why Integrate sus?

When AI agents install packages autonomously, they don't verify package integrity or check for known vulnerabilities. This makes them vulnerable to:

• Typosquatting - installing lodashs instead of lodash
• Supply chain attacks - compromised packages like event-stream
• Malicious install scripts - packages that execute code during installation

With sus integration, every package installation is scanned for vulnerabilities before proceeding.

Prerequisites

• sus CLI installed
• Codex CLI

Option A: AGENTS.md Instructions (Recommended)

Codex reads AGENTS.md files before doing any work. This is the simplest way to instruct Codex to use sus for package installations.

Project-level instructions

Create .codex/AGENTS.md in your project root:

## Package Installation Rules
 
Always use `sus` instead of direct package manager commands:
 
- Use `sus add <package>` instead of `npm install`, `yarn add`, `pnpm add`, `bun add`
- Use `sus remove <package>` instead of `npm uninstall`, `yarn remove`
- Use `sus scan` to audit existing dependencies
 
This ensures all packages are scanned for vulnerabilities, malicious code,
and supply chain risks before installation.
 
### Why sus?
 
sus is a package gateway that scans packages for:
- Known CVEs and vulnerabilities
- Malicious install scripts
- Obfuscated code and prompt injection
- Supply chain attack indicators
 
Never bypass sus by running package manager commands directly.

Global instructions

To apply these instructions to all your projects, create ~/.codex/AGENTS.md:

mkdir -p ~/.codex

Then add the same content to ~/.codex/AGENTS.md.

How AGENTS.md works

Codex discovers instruction files in this order:

1. Global: ~/.codex/AGENTS.md
2. Project: .codex/AGENTS.md (in trusted projects)
3. Nested: Files closer to your working directory override earlier ones

Files are concatenated, with later files taking precedence. Use AGENTS.override.md for temporary overrides without deleting the base file.

Option B: Rules (Experimental, Enforcement)

For stricter enforcement, use Codex's experimental Rules system to block package manager commands entirely.

Create the rules file

Create .codex/rules/sus.rules:

# Block npm install commands
prefix_rule(
  pattern=["npm", ["install", "i", "add"]],
  decision="forbidden",
  justification="Use `sus add <package>` instead for security scanning.",
  match=["npm install express", "npm i lodash", "npm add react"],
  not_match=["npm run build", "npm test"],
)
 
# Block yarn add commands
prefix_rule(
  pattern=["yarn", "add"],
  decision="forbidden",
  justification="Use `sus add <package>` instead for security scanning.",
  match=["yarn add express", "yarn add -D typescript"],
)
 
# Block pnpm add commands
prefix_rule(
  pattern=["pnpm", ["add", "i", "install"]],
  decision="forbidden",
  justification="Use `sus add <package>` instead for security scanning.",
  match=["pnpm add express", "pnpm i lodash"],
)
 
# Block bun add commands
prefix_rule(
  pattern=["bun", ["add", "i", "install"]],
  decision="forbidden",
  justification="Use `sus add <package>` instead for security scanning.",
  match=["bun add express", "bun i lodash"],
)
 
# Block pip install commands
prefix_rule(
  pattern=["pip", "install"],
  decision="forbidden",
  justification="Use `sus add <package>` instead for security scanning.",
  match=["pip install requests", "pip install -r requirements.txt"],
)
 
# Block cargo add commands
prefix_rule(
  pattern=["cargo", "add"],
  decision="forbidden",
  justification="Use `sus add <package>` instead for security scanning.",
  match=["cargo add serde", "cargo add tokio"],
)

Understanding rules

Rules use Starlark syntax (Python-like) and support these fields:

Test your rules

Use codex execpolicy check to verify rules work as expected:

codex execpolicy check --pretty \
  --rules .codex/rules/sus.rules \
  -- npm install express

Expected output shows the command is forbidden with the justification message.

Global rules

Place rules in ~/.codex/rules/sus.rules to apply them to all projects:

mkdir -p ~/.codex/rules
cp .codex/rules/sus.rules ~/.codex/rules/

How It Works

When Codex tries to install a package:

With AGENTS.md: Codex reads the instructions and chooses to use sus (soft enforcement).

With Rules: Codex is blocked from running npm install and must use sus (hard enforcement).

Command Mapping

Instruct Codex to use these mappings:

Testing the Integration

Ask Codex to install a package:

Install the express package

With proper configuration, Codex should use sus:

🔍 checking express@4.21.0...
✅ not sus
   ├─ publisher: expressjs (verified)
   ├─ downloads: 32M/week
   ├─ cves: 0
   └─ install scripts: none
📦 installed
📝 updated AGENTS.md docs index

Troubleshooting

Instructions not loading

1. Verify the file exists at .codex/AGENTS.md
2. Check that the project is trusted (Codex skips untrusted project files)
3. Verify the file is not empty
4. Run codex --ask-for-approval never "Summarize the current instructions." to check what Codex loaded

Rules not applying

1. Verify the rules file exists at .codex/rules/sus.rules
2. Test with codex execpolicy check
3. Check for syntax errors in the Starlark file
4. Restart Codex after adding rules

Codex still uses npm directly

1. Make instructions more explicit and emphatic
2. Use Rules with decision="forbidden" for hard enforcement
3. Check for conflicting instructions in nested AGENTS.md files

Comparison: AGENTS.md vs Rules

Recommendation: Start with AGENTS.md for simplicity. Add Rules if you need stricter enforcement.

Next Steps

• Learn about threat detection
• Learn about AGENTS.md
• See other integration guides