agentinel 0.0.1 → 0.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +163 -70
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,104 +1,197 @@
1
- # agentinel
1
+ <div align="center">
2
+ <img src="assets/banner.jpg" alt="Agentinel Banner" width="100%" />
2
3
 
3
- Guards your AI coding agent when it installs npm packages.
4
+ [![npm version](https://img.shields.io/npm/v/agentinel.svg?style=flat-square)](https://www.npmjs.com/package/agentinel)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
6
+ [![Node.js CI](https://img.shields.io/github/actions/workflow/status/aman-janwani/agentinel/publish.yml?style=flat-square)](https://github.com/aman-janwani/agentinel/actions)
7
+ </div>
4
8
 
5
- Coding agents install dependencies on your behalf, often without you looking closely. Sometimes
6
- they install a package that was registered last week with no history, sometimes one whose name they
7
- invented, and sometimes a legitimate package that pulls in a compromised one three levels deep.
8
- agentinel checks every package an install would bring in, at the moment the agent reaches for it,
9
- and tells the agent why something looks wrong so it can back off.
9
+ <br />
10
10
 
11
- Every other tool in this space guards your terminal. agentinel guards your agent.
11
+ > **The zero-cost, locally-run package guardrail for your AI coding agents.**
12
12
 
13
- ## Install
13
+ *Agentinel guards your AI agent when it installs npm packages, catching hallucinated dependencies, slopsquatting, and malicious packages before they execute on your machine.*
14
+
15
+ ---
16
+
17
+ ## 📖 The Problem
18
+
19
+ AI coding agents (like Claude Code, Copilot, or Cursor) install dependencies on your behalf, often while you aren't looking closely.
20
+ - Sometimes they install a package that was registered last week with no history.
21
+ - Sometimes they install a package whose name they entirely **hallucinated**.
22
+ - Sometimes, they install a legitimate package that pulls in a compromised one three levels deep.
23
+
24
+ **Agentinel** checks every package an install would bring in, at the exact moment the agent reaches for it. It evaluates the package against a bundled, locally-run database of over 216,000 known malicious packages and zero-cost registry heuristics. It then tells the agent why something looks wrong so the AI can back off and reconsider.
25
+
26
+ Every other tool in this space guards your terminal. **Agentinel guards your agent.**
27
+
28
+ ---
29
+
30
+ ## ⚡ Features & Security Philosophy
31
+
32
+ - **Zero-Cost & Private:** Agentinel does no network interception, runs no cloud proxies, and requires no paid APIs. The malware list is matched locally.
33
+ - **Deep Tree Scanning:** Checks every package an install would *actually* bring in, not just the one named. (`npm install express` brings in 67 packages. We check all 67).
34
+ - **Known Malware:** Bundles a local OSV database of 216,000+ confirmed malicious packages.
35
+ - **Zero False Positives on Popular Packages:** Tested against the top 100 npm packages.
36
+ - **Heuristic Scanning:** Flags npm takedowns, packages under 30 days old with < 1k downloads (slopsquatting), publisher drift, and non-existent hallucinated names.
37
+ - **Fails Open:** Designed so that if it crashes or can't reach the registry, it fails open. It will never permanently wedge your terminal or block your work.
38
+
39
+ ---
40
+
41
+ ## 🚀 Installation
42
+
43
+ Install it as a dev-dependency in your repository:
14
44
 
15
45
  ```sh
16
- npm install --save-dev agentinel && npx asen init
46
+ npm install --save-dev agentinel
47
+ npx asen init
17
48
  ```
49
+ *(No account, no server, no complex configuration.)*
18
50
 
19
- That sets up a hook for whichever coding agents you use, plus a git pre-commit hook. No account, no
20
- server, no configuration.
51
+ ---
21
52
 
22
- You can also try it with `npx agentinel init` and nothing installed, though the agent hook then
23
- resolves through npx on every command, which is slower.
53
+ ## 🤖 1. Agentic Use (Native Hooks)
24
54
 
25
- ## What it checks
55
+ Agentinel wires itself directly into the native pre-execution hooks of popular CLI agents: **Claude Code, Codex CLI, Copilot CLI, and Gemini CLI**.
26
56
 
27
- Every package an install would actually bring in, not just the one you named. `npm install express`
28
- looks like one package and installs 67, and most real npm malware hides in the transitive ones.
57
+ When an agent attempts to run `npm install`, Agentinel intercepts the event (e.g., `PreToolUse` for Claude) and scans the requested dependency tree.
29
58
 
30
- - **Known malware.** A bundled list of 216,000 packages confirmed malicious (from the open OSV
31
- database), matched on your machine. Nothing about what you install is ever sent anywhere.
32
- - **npm takedowns.** Packages npm itself has pulled for security.
33
- - **New and unused.** Registered in the last 30 days with under 1,000 monthly downloads, the classic
34
- slopsquat shape.
35
- - **No track record.** No repository, one version ever, barely downloaded.
36
- - **Sudden bloat.** A patch release that triples the amount of code, paired with a change of
37
- publisher: the fingerprint of a hijacked maintainer account.
59
+ ### How it feeds back to the AI
60
+ If Agentinel flags a package, it feeds the context *back* to the AI agent in a concise format the agent understands, rather than just crashing the terminal.
38
61
 
39
- Names that do not exist on npm at all are called out too, since a name an agent invented is exactly
40
- what a slopsquatter waits to register.
62
+ **Example Intercept:**
63
+ ```json
64
+ {
65
+ "hookEvent": "PreToolUse",
66
+ "action": "BLOCK",
67
+ "reason": "agentinel blocked 'react-router-v7-beta': Package does not exist on npm (hallucination)."
68
+ }
69
+ ```
70
+ The AI reads this, realizes the package is fake or malicious, and intelligently searches for the correct alternative instead of blindly retrying.
41
71
 
42
- Against the 100 most depended-on packages on npm it flags **zero** of them, while catching every
43
- package in its known-bad test set. A security tool that cries wolf gets uninstalled the same day, so
44
- that number is the one that matters.
72
+ ---
45
73
 
46
- ## Which agents
74
+ ## 🧑‍💻 2. Normal / Human Use (The Shim)
47
75
 
48
- CLI agents, all through their native pre-execution hook: **Claude Code, Codex CLI, Copilot CLI, and
49
- Gemini CLI**. `asen init` wires up whichever of them it finds on your machine. When it blocks
50
- something in strict mode, the agent is told why in a way it understands, so it looks for a safe
51
- alternative instead of retrying.
76
+ What about installs that never go through an agent? (e.g., You typing `npm install` manually).
52
77
 
53
- For installs that never go through an agent, a person typing `npm i` by hand or a script shelling
54
- out, there is an opt-in shim (`asen init --shim`) that checks those too. And the git pre-commit hook
55
- scans the staged lockfile, so a poisoned dependency cannot slip in through a commit either.
78
+ Agentinel provides an opt-in **PATH shim**.
56
79
 
57
- ## Warn or block
80
+ ```sh
81
+ npx asen init --shim
82
+ ```
58
83
 
59
- Warn is the default: it tells you and the agent, and gets out of the way. Set `"mode": "strict"` in
60
- `.agentinel.json` to turn a finding into a block.
84
+ This puts a tiny, fail-open wrapper script earlier in your `PATH`. When you type `npm install`, the shim checks the package first. If it's safe, the real `npm` command runs instantly.
61
85
 
62
- ## Commands
86
+ **Terminal Example:**
87
+ ```bash
88
+ $ npm install left-pad-malicious
63
89
 
64
- ```sh
65
- npx asen init # set up hooks in this repo
66
- npx asen init --shim # also guard installs you type by hand
67
- asen check # check the staged dependencies now
68
- asen check some-package # check a specific package
69
- asen allow <pkg> --reason "why" # allowlist a package, with a logged reason
70
- asen unshim # remove the shim
90
+ ⚠️ agentinel warning: left-pad-malicious is 2 days old and has 12 downloads.
91
+ This matches the profile of a slopsquatting or malicious package.
71
92
  ```
72
93
 
73
- `asen check` exits non-zero when something is flagged, so it works as a CI step.
94
+ ---
95
+
96
+ ## 🔒 3. The Git Pre-Commit Hook
97
+
98
+ As a final safety net, `asen init` installs a Git pre-commit hook.
99
+ Before you can commit a change to `package-lock.json`, Agentinel scans the staged lockfile. If a poisoned dependency slipped in somehow, the commit is flagged, ensuring malware never reaches your `main` branch.
100
+
101
+ ---
102
+
103
+ ## ⚖️ Competitors vs. Us
74
104
 
75
- The allowlist lives in `.agentinel.json` and is committed, so the reason a package was trusted is
76
- visible to everyone on the repo. It is a trail, not a silent bypass.
105
+ How do we stack up against traditional commercial security scanners?
77
106
 
78
- ## How it stays out of your way
107
+ | Feature | Agentinel (Us) | Commercial Alternatives |
108
+ |---|---|---|
109
+ | **Cost Model** | **100% Free / Zero-cost** | Monthly Subscriptions |
110
+ | **Data Privacy** | **100% Local (No cloud)** | Sends telemetry/code to cloud |
111
+ | **Agent Hooking** | **Native (intercepts AI directly)** | Scans terminal post-facto |
112
+ | **Feedback Loop** | **Tells AI *why* it failed** | Just blocks the terminal |
113
+ | **Setup** | **Zero-config, drop-in** | Requires API keys & accounts |
114
+ | **Malware Database** | Local OSV Feed (~216k pkgs) | Proprietary Feeds |
115
+ | **Feed Freshness** | *Lags 1-3 days behind OSV* | Real-time / Minutes |
116
+ | **Detection Method** | *Version-exact + Heuristics* | Advanced Behavioral Analysis |
79
117
 
80
- agentinel does no network interception. It runs no proxy, changes no TLS settings, and injects no
81
- environment variables. So it cannot break `npm test`, a private registry, or a Rust or Go build, the
82
- way a man-in-the-middle proxy can. The malware list is matched locally and works offline. If the npm
83
- API is unreachable, a check is skipped with a note rather than blocking your work.
118
+ *Note: We currently lag slightly on feed freshness (by a few days) and advanced behavioral analysis compared to paid enterprise tools. These are areas we acknowledge and plan to explore and improve in future versions, without compromising our zero-cost, 100% local philosophy.*
84
119
 
85
- ## Platforms
120
+ ---
86
121
 
87
- macOS and Linux are fully supported. Windows works too: the agent hooks and the git pre-commit hook
88
- run, and the optional shim installs as a PowerShell-friendly wrapper. Windows is written and covered
89
- by tests but has had less real-world use than macOS and Linux, so if something misbehaves there,
90
- please open an issue.
122
+ ## ⚙️ Configuration (Warn vs. Block)
123
+
124
+ By default, Agentinel runs in **Warn Mode**. It alerts you (and the agent) but gets out of the way.
125
+ To strictly block bad packages, change your `.agentinel.json` file to strict mode:
126
+
127
+ ```json
128
+ {
129
+ "mode": "strict",
130
+ "allowlist": {}
131
+ }
132
+ ```
133
+
134
+ ---
135
+
136
+ ## 🧰 Command Reference
137
+
138
+ Here are all the commands you can run via `npx asen <command>`:
139
+
140
+ ### `npx asen init`
141
+ Wires up agent hooks and git hooks in the current repo.
142
+ ```bash
143
+ $ npx asen init
144
+ ✅ Wired up pre-commit git hook.
145
+ ✅ Wired up Claude Code PreToolUse hook.
146
+ ```
147
+
148
+ ### `npx asen init --shim`
149
+ Wires up hooks AND installs the global PATH shim for human terminal protection.
150
+ ```bash
151
+ $ npx asen init --shim
152
+ ✅ Shim installed. Native terminal npm commands are now guarded.
153
+ ✅ Wired up pre-commit git hook.
154
+ ```
155
+
156
+ ### `npx asen check`
157
+ Scans the currently staged dependencies in your lockfile. Exits non-zero if flagged (great for CI/CD pipelines).
158
+ ```bash
159
+ $ npx asen check
160
+ Scanning staged dependencies...
161
+ ✅ All 142 staged packages passed security checks.
162
+ ```
163
+
164
+ ### `npx asen check <package-name>`
165
+ Scans a specific package instantly without installing it.
166
+ ```bash
167
+ $ npx asen check react-router-v7-fake
168
+ ⚠️ agentinel warning: react-router-v7-fake is 1 day old and has 4 downloads.
169
+ This matches the profile of a slopsquatting or malicious package.
170
+ ```
171
+
172
+ ### `npx asen allow <package-name> --reason "why"`
173
+ Adds a package to the allowlist in `.agentinel.json` with a required reason. This provides an audited trail for your team.
174
+ ```bash
175
+ $ npx asen allow my-internal-pkg --reason "Internal company package not on public npm"
176
+ ✅ Added my-internal-pkg to .agentinel.json allowlist.
177
+ ```
178
+
179
+ ### `npx asen unshim`
180
+ Removes the global PATH shim.
181
+ ```bash
182
+ $ npx asen unshim
183
+ ✅ Shim removed. Normal npm path restored.
184
+ ```
91
185
 
92
- ## Scope
186
+ ---
93
187
 
94
- The npm registry only, which covers npm, pnpm, yarn, and bun, since they all install from it. Not a
95
- CVE scanner, that is what `npm audit`, Snyk, and Dependabot are for. This finds malicious packages,
96
- not vulnerable-but-legitimate ones.
188
+ ## 🤝 Contributing & Maintainers
97
189
 
98
- ## Contributing
190
+ We welcome contributions!
191
+ - Please read our [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, the zero-cost architecture rules, and the process for submitting pull requests.
99
192
 
100
- See [CONTRIBUTING.md](CONTRIBUTING.md).
193
+ **Maintainer:** [Aman Janwani](https://github.com/aman-janwani)
101
194
 
102
- ## License
195
+ ## 📄 License
103
196
 
104
- MIT. See [LICENSE](LICENSE).
197
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentinel",
3
- "version": "0.0.1",
3
+ "version": "0.0.10",
4
4
  "description": "Catches AI hallucinated npm packages before an agent installs them",
5
5
  "license": "MIT",
6
6
  "author": "Aman Janwani",