KR 한국어

n2-ark

AI Firewall — If the AI can't solve the logic, it can't do anything.

A rogue AI won't follow the rules — so n2-ark makes it impossible to skip them.

The Solution

n2-ark is a code-level AI firewall with a direct human approval channel. It doesn't ask the AI to behave — it makes misbehavior physically impossible.

AI Agent (any model, any platform)
 | action request
 v
+------------------------------+      +---------------------+
|         n2-ark Gate          |      | Approval Dashboard  |
|                              |      | localhost:9720      |
|  Pass  --> execute           | <--> | (Human only,        |
|  Block --> hard error        |      |  AI cannot reach)   |
+------------------------------+      +---------------------+
 | only approved actions
 v
 Actual Execution

Not a soft warning. A hard gate. The action literally cannot execute.

Quick Start

npm install n2-ark

const { createArk } = require('n2-ark');

const ark = createArk({ rulesDir: './rules' });

const result = ark.check('execute_command', 'rm -rf /home/user');

if (!result.allowed) {
 console.log('BLOCKED:', result.reason);
 // "Blocked by blacklist rule 'catastrophic_destruction'"
}

What's New in v3.x (Migration Guide)

Version 3 is a major security hardening release focused on eliminating AI self-approval vectors and obfuscation bypasses:

• MCP ark_approve Removed: The AI can no longer approve actions via MCP. Approvals are strictly out-of-band via the HTTP Dashboard (localhost:9720) or CLI (npx n2-ark approve).
• Enhanced Normalization: The ark.check evaluator now automatically neutralizes shell subexpressions ($(), ${}), command caret stripping (^), and URL encoding before evaluating regex rules.
• Strict CORS & Loopbacks: The Approval Server now strictly enforces same-origin policies to prevent CSRF attacks, and blocks all variant loopback addresses (127.1, [::1], 0.0.0.0) from being accessed by the AI.

Migration: No API changes to createArk() or ark.check(). If you previously allowed agents to use ark_approve, you must now manually approve via browser or terminal.

Integration & Enforcement

n2-ark provides the rules engine. How you integrate it determines whether it's a real firewall or just a suggestion.

| Level | Method | Enforcement | |-------|--------|-------------| | Library | Import and call ark.check() before every tool execution | Code-level — true enforcement | | MCP Server | Connect as MCP server, AI is instructed to check | Prompt-level — cooperative enforcement | | Approval Server | Localhost dashboard, human approves directly | Out-of-band — AI cannot interfere |

As a Library (True Enforcement)

const { createArk } = require('n2-ark');
const ark = createArk({
 rulesDir: './rules',
 approvalServer: true,  // enable direct approval channel
});

async function executeTool(name, args) {
 const check = ark.check(name, JSON.stringify(args));
 if (!check.allowed) {
  throw new Error(`BLOCKED: ${check.reason}`);
 }
 return await actualToolExecution(name, args);
}

As MCP Server

For Claude Desktop, Cursor, Windsurf, and other MCP hosts:

{
 "mcpServers": {
  "n2-ark": {
   "command": "npx",
   "args": ["-y", "n2-ark"]
  }
 }
}

MCP server mode does not physically force the AI to call ark_check. For true enforcement, integrate as a library. The approval server runs automatically in MCP mode to provide a direct human channel.

The Default Ruleset

npm install n2-ark gives you a production-ready ruleset that works immediately. No configuration needed.

180 regex patterns across 17 rules, covering 10 threat categories. Zero configuration. Sub-millisecond per check.

Philosophy

Normal development work is NEVER blocked. npm install, node script.js, git push, curl POST, rm file.txt — all free. Only truly catastrophic or unauthorized actions are blocked.

10 Threat Categories

| # | Category | What It Blocks | |---|----------|---------------| | 1 | Catastrophic Destruction | rm -rf /, format C:, DROP DATABASE, dd of=/dev/sda, rd /s /q | | 2 | Data Exfiltration | Reverse shells, ngrok, pastebin, transfer.sh | | 3 | Credential Theft | SSH keys, AWS credentials, /etc/shadow, GPG exports | | 4 | Supply Chain Attacks | npm install -g, npm publish, postinstall scripts | | 5 | Git History Destruction | push --force, reset --hard, remote URL changes | | 6 | External Communication | Email, SMS, phone calls, Slack/Discord webhooks | | 7 | Financial APIs | stripe.com, paypal.com, braintree direct API calls | | 8 | Crypto Mining | xmrig, cpuminer, stratum+tcp | | 9 | Self-Protection | .n2 file edits, ark manipulation, core file modification | | 10 | Wildcard Destruction | rm *, del *.*, shred, Remove-Item *, Remove-Item -Recurse |

What Is NOT Blocked

npm install express     OK  (local installs are free)
node server.js          OK
python train.py         OK
rm old-file.txt         OK  (individual file deletion is fine)
git push origin main    OK  (only --force is blocked)
npx create-next-app     OK
curl -X POST api.com    OK  (general HTTP requests are free)
kill -9 12345           OK
"implement payment"     OK  (writing payment code is free)
"send message to user"  OK  (chat/messaging app code is free)

Cat 7 (Financial) only blocks direct API endpoint calls to payment processors (stripe.com, paypal.com, etc.). Writing payment integration code is allowed — calling the live API is blocked.

Quad-Layer Self-Protection

Layer 1: .n2 file paths detected          --> BLOCKED
Layer 2: manipulation verbs + n2-ark      --> BLOCKED
Layer 3: core + infra files (gate, parser, setup, integrity) --> BLOCKED
Layer 4: approval CLI/HTTP/IPv6 self-approval  --> BLOCKED

Approval Server

The biggest problem with AI firewalls: the AI sits between you and the firewall. A rogue AI can fake approvals.

n2-ark solves this with a localhost approval server — a direct channel between you and the firewall that the AI cannot reach.

                    MCP (JSON-RPC, stdin/stdout)
You  <-->  AI  <------------------------->  n2-ark
 |                                            |
 +-------- http://localhost:9720 -------------+
 |         Direct approval channel            |
 +-------- npx n2-ark approve ----------------+
           CLI approval (separate terminal)

Why the AI Cannot Reach It

In MCP architecture, the AI is sandboxed — it communicates exclusively through stdin/stdout JSON-RPC. It has no ability to make HTTP requests to localhost:9720.

Even if the AI has shell access via run_command, Layer 4 self-protection blocks:

• npx n2-ark approve / npx n2-ark deny commands
• node dist/cli.js approve / deny direct execution
• curl localhost:9720/api/approve/... HTTP calls
• curl 127.0.0.1:9720/api/deny/... variants
• curl 0.0.0.0:9720/api/approve/... alternative loopback
• curl [::1]:9720/api/approve/... IPv6 loopback

Enable It

As a library:

const ark = createArk({
 rulesDir: './rules',
 approvalServer: true,               // default port 9720
 // approvalServer: { port: 8080 },  // custom port
});

As MCP Server (enabled by default):

# Disable with env var:
N2_ARK_APPROVAL=false npx n2-ark

# Custom port:
N2_ARK_APPROVAL_PORT=8080 npx n2-ark

Browser Dashboard

Open http://localhost:9720 to see pending approvals and click Approve/Deny.

CLI Commands (separate terminal)

# List all approval requests
npx n2-ark approve

# Approve a specific request by ID
npx n2-ark approve A7F3

# Deny a specific request
npx n2-ark deny A7F3

# Interactive watch mode -- polls and prompts for each new request
npx n2-ark approve --watch

Security Model

As of v3.0.3, ark_approve has been removed from MCP. The AI has zero approval paths.

| Channel | AI Accessible | Out-of-band | Layer 4 Protected | |---------|:---:|:---:|:---:| | HTTP Dashboard (localhost:9720) | ❌ | ✅ | ✅ | | CLI (npx n2-ark approve) | ❌ | ✅ | ✅ | | MCP (removed) | — | — | — |

Constitutional rules cannot be approved through any channel.

REST API

| Endpoint | Method | Description | |----------|--------|-------------| | / | GET | Dashboard UI | | /api/pending | GET | Pending approvals | | /api/all | GET | All requests | | /api/approve/:id | POST | Approve a request | | /api/deny/:id | POST | Deny a request | | /api/status | GET | Summary counts |

Domain-Specific Extensions

The default ruleset is a universal safety layer. Domain experts can add industry-specific rules.

cp node_modules/n2-ark/examples/medical.n2 ./rules/

| File | Domain | For Whom | |------|--------|----------| | financial.n2 | Finance | FinTech, security officers | | system.n2 | DevOps | SRE, ops engineers | | medical.n2 | Healthcare | Medical IT, EMR | | military.n2 | Defense | Defense systems | | privacy.n2 | Privacy | DPOs, privacy engineers | | autonomous.n2 | Autonomous | Self-driving, drones | | legal.n2 | Legal | LegalTech |

Multiple .n2 files can be used simultaneously in your rules/ directory.

Audit Logging

Every decision is automatically recorded.

data/audit/
  2026-04-03.jsonl
  2026-04-02.jsonl
  ...

{
 "timestamp": "2026-04-03T01:48:38.123Z",
 "decision": "BLOCK",
 "action": "execute_command",
 "rule": "financial_actions",
 "reason": "Blocked by blacklist rule 'financial_actions'",
 "pattern": "/stripe\\.com/i"
}

MCP Tools

| Tool | Description | |------|-------------| | ark_check | Check if an action is allowed. Call before ANY action. | | ark_status | View loaded rules and state machine states. | | ark_load_rules | Load additional rules at runtime. | | ark_stats | Audit stats: blocked vs passed over N days. | | ark_reset | Reset state machines for a new session. |

ark_approve was removed from MCP in v3.0.3 to eliminate AI self-approval vectors. Human approval is only available via the HTTP Dashboard or CLI.

.n2 Rule Syntax

@rule — Blacklist Patterns

@rule dangerous_commands {
 scope: all
 blacklist: [/rm\s+-rf/i, /DROP\s+TABLE/i]
 requires: human_approval
}

@gate — Approval Required

@gate high_risk {
 actions: [deploy_production, send_email, make_purchase]
 requires: human_approval
 min_approval_level: 1
}

@contract — Sequence Enforcement

@contract deploy_sequence {
 idle -> building : on build_start
 building -> testing : on run_tests
 testing -> production : on deploy_production
}

API Reference

createArk(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | rulesDir | string | ./rules | .n2 rule files directory | | setupFile | string | ./ark.setup.yaml | YAML setup file path | | auditDir | string | ./data/audit | Audit log directory | | strictMode | boolean | false | Block unknown actions | | auditEnabled | boolean | true | Enable audit logging | | auditPasses | boolean | false | Log passed actions too | | approvalServer | boolean or object | false | Enable direct approval dashboard (true or { port: 9720 }) |

Methods

| Method | Description | |--------|-------------| | ark.check(name, content?, type?) | Check action. Returns { allowed, reason?, rule?, pendingId?, approvalUrl? } | | ark.approve(ruleName, actionName) | Grant approval for a general rule | | ark.loadString(source) | Load additional rules at runtime | | ark.summary() | Get rules summary | | ark.stats(days?) | Audit statistics | | ark.reset() | Reset state machines | | ark.close() | Shutdown (stops approval server, flushes audit) |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | N2_ARK_RULES | ./rules | Rules directory path | | N2_ARK_SETUP | ./ark.setup.yaml | Setup file path | | N2_ARK_STRICT | false | Enable strict mode | | N2_ARK_APPROVAL | true (MCP) | Enable approval server | | N2_ARK_APPROVAL_PORT | 9720 | Approval server port |

Design Philosophy

1. Zero Trust — Never trust the AI's intentions
2. Code over Prompts — Rules are compiled, not suggested
3. Hard Gates — Blocked means blocked, no soft warnings
4. Sandbox Isolation — Approval channel is unreachable from the AI's sandbox
5. Zero Dependencies — Pure Node.js, nothing to break
6. Auditable — Every decision is logged
7. The Last Shield — Normal work is free, only the truly dangerous is blocked

License

Dual License — Free for non-commercial, personal, educational, and open-source use under Apache 2.0. Commercial use requires a separate license. See LICENSE for details.

nton2.com | npm | [email protected]