sentrion 1.0.0 → 2.0.0

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 +87 -166
  2. package/package.json +7 -2
package/README.md CHANGED
@@ -1,214 +1,135 @@
1
1
  # Sentrion
2
2
 
3
- **A live guard for developer machines.** Put `sentrion` in front of any command —
4
- a package install or a program in any language — and it scans, watches and
5
- blocks malicious install scripts, credential theft, backdoors and privilege
6
- escalation, with a Kill / Allow prompt and a readable incident report.
3
+ Sentrion is a runtime security guard for developers. Run commands through
4
+ Sentrion to block malicious package scripts, credential theft, backdoors,
5
+ network abuse, and other risky behavior.
7
6
 
8
- > One engine. Linux, macOS and Windows. Zero npm dependencies.
7
+ ## Install
9
8
 
10
9
  ```bash
11
- npm install -g sentrion
12
-
13
- sentrion npm install express # guard a package install
14
- sentrion python3 app.py # guard untrusted code you were asked to run
15
- sentrion scan ./interview-task # look before you run — nothing executes
10
+ npm i -g sentrion
16
11
  ```
17
12
 
18
- Built by **imeerai** · open source by [imeer.ai](https://imeer.ai) ·
19
- repo: <https://github.com/imeerai/sentrion>
20
-
21
- ---
22
-
23
- ## Why
24
-
25
- Supply-chain attacks now run code on *your* machine with *your* privileges:
26
-
27
- - **Shai-Hulud 2.0** (Nov 2025) — 700+ npm packages; a `preinstall` script stole
28
- tokens and republished the victim's own packages.
29
- - **Axios compromise** (Mar 2026) — a poisoned transitive dependency shipped a
30
- remote-access trojan to anyone who installed.
31
- - **Contagious Interview** (DPRK) — a "debug this code" job task; the victim runs
32
- the repo and hands over a backdoor.
33
-
34
- Blocking install scripts (npm v12) removes one trigger, not the capability: code
35
- still runs at import time, at `npm start`, or when you run the repo. Sentrion
36
- guards the **whole developer loop** — install, import and first run.
37
-
38
- ## What it does
39
-
40
- | Stage | Sentrion |
41
- | --- | --- |
42
- | **Before code runs** | resolves every package, checks a malware list, publish age, typosquats, new install scripts, obfuscation, and repo traps (`.vscode/tasks.json`, `curl \| sh`). |
43
- | **Prepare** | swaps real tokens for **canaries**, starts an egress proxy (registry hosts only), injects language hooks, puts the run in a **containment group**. |
44
- | **While it runs** | two sensor tiers watch the process tree, file reads, network and persistence, and tie every event back to the package that caused it. |
45
- | **Decision** | a rule fires → **pause** → `K` kill · `A` allow once · `P` always trust. In CI, any risky event fails the command. |
46
- | **After** | one **incident** per attack chain: what ran, which rule, what was prevented, what to do — as text, JSON and SARIF. |
47
-
48
- ## Install
13
+ Or install it locally in a project:
49
14
 
50
15
  ```bash
51
- npm install -g sentrion
52
- sentrion --help
53
- sentrion doctor # what this OS lets Sentrion see and block
16
+ npm i sentrion
17
+ npx sentrion --help
54
18
  ```
55
19
 
56
- Use it every time by adding shell aliases:
20
+ Requires Node.js 18 or newer.
21
+
22
+ ## Quick Start
57
23
 
58
24
  ```bash
59
- eval "$(sentrion shell-init)" # npm -> sentrion npm, pip -> sentrion pip, ...
25
+ sentrion npm install express
26
+ sentrion pnpm add zod
27
+ sentrion pip install requests
28
+ sentrion python3 app.py
29
+ sentrion scan ./project
60
30
  ```
61
31
 
32
+ `scan` checks a package or project without executing it.
33
+
62
34
  ## Usage
63
35
 
64
36
  ```bash
65
- # guard any command
37
+ # Package managers
66
38
  sentrion npm install express
67
- sentrion pnpm add zod # also yarn, bun, npx, pnpx, bunx
68
- sentrion pip install requests # also uv, poetry, pipx
69
- sentrion python3 app.py # any language / runtime
70
- sentrion run -- node server.js # explicit form (use after flags)
71
-
72
- # look before running — nothing executes
39
+ sentrion pnpm add zod
40
+ sentrion yarn add zod
41
+ sentrion bun add zod
42
+ sentrion npx create-react-app my-app
43
+
44
+ # Python package managers
45
+ sentrion pip install requests
46
+ sentrion uv add requests
47
+ sentrion poetry add requests
48
+
49
+ # Run code
50
+ sentrion python3 app.py
51
+ sentrion node app.js
52
+ sentrion run -- node server.js
53
+
54
+ # Scan
73
55
  sentrion scan express@4.21.2
74
- sentrion scan . # this repo / a fresh clone
75
- sentrion test -- node app.js # run in a throwaway sandbox (enforce + temp HOME)
76
-
77
- # decisions & evidence
78
- sentrion report --last # or: --all | <id>
79
- sentrion report <id> --format sarif # export for CI code scanning (also --json)
80
- sentrion rules # list the rule set; sentrion rules NET-01 for one
81
-
82
- # settings you control
83
- sentrion mode audit # set your default mode
84
- sentrion trust esbuild@^0.20 # allow one package (narrow, pinned); untrust removes
85
- sentrion allow NET-02 # set one rule to allow in your policy
86
- sentrion init # scaffold ./.sentrion.json for this repo
87
- sentrion update # refresh the malware + typosquat lists scan uses
88
- sentrion policy show # the effective, merged policy
89
- sentrion shell-init # print aliases
56
+ sentrion scan ./project
57
+
58
+ # Reports
59
+ sentrion report --last
60
+ sentrion rules
90
61
  sentrion doctor
62
+ sentrion --help
91
63
  ```
92
64
 
93
- Every command accepts `--json` (machine-readable, for CI) and `--quiet`
94
- (only blocks and prompts show).
65
+ Every command supports `--json` for machine-readable output and `--quiet` for
66
+ minimal output.
95
67
 
96
- ### Modes
68
+ ## Modes
97
69
 
98
- | Mode | On a risky event |
70
+ | Mode | Behavior |
99
71
  | --- | --- |
100
- | `prompt` *(default)* | pause and ask: **K** kill / **A** allow once / **P** trust |
101
- | `enforce` | block per policy, never ask (servers, CI, `--ci`) |
102
- | `audit` | log only, block nothing (first week, tuning) |
103
- | `learn` | record normal behaviour and propose allow rules |
72
+ | `prompt` | Pause and ask whether to kill, allow once, or trust |
73
+ | `enforce` | Block risky actions without prompting |
74
+ | `audit` | Record risky actions without blocking |
75
+ | `learn` | Observe behavior and suggest trust rules |
104
76
 
105
77
  ```bash
106
- sentrion --mode audit npm install some-pkg
107
- sentrion --ci npm install # non-interactive; any ask/block = exit 87
78
+ sentrion mode audit
79
+ sentrion mode enforce
80
+ sentrion --mode audit npm install express
81
+ sentrion --ci npm install
108
82
  ```
109
83
 
110
- ## How it works
111
-
112
- Two sensor tiers share one rule engine and one policy; only a thin platform
113
- layer differs per OS.
114
-
115
- - **Tier 1 — language hooks.** For Node, a preload (`--require`) wraps
116
- `child_process`, `net`/`http(s)`, secret-file reads and persistence writes;
117
- for Python, a `sitecustomize` installs PEP 578 audit hooks over `open`,
118
- `socket.connect`, `subprocess`/`os.system`. The hook decides **before** the
119
- action happens, so a blocked connect or secret read never completes. It also
120
- tells you *which package* made the call.
121
- - **Egress proxy.** A local allowlist proxy is set via `HTTP(S)_PROXY`, so even
122
- child processes the hooks don't instrument (e.g. `pip`) can only reach
123
- allowlisted registries.
124
- - **Fail-closed.** If the guard is killed, it takes the whole process group with
125
- it, so nothing is left running unguarded.
126
- - **Tier 2 — OS sensors.** The parent enumerates and can kill the whole process
127
- group (`/proc` + process groups on Linux, `ps` on macOS, Win32 + Job Objects
128
- on Windows), catching native code and any runtime the language hook can't see
129
- (e.g. a payload that starts Bun to dodge Node monitoring).
130
-
131
- A guarded run executes inside a **containment group**; on a block the group is
132
- killed, the egress proxy keeps holding the connection, and the package is
133
- quarantined. Admin-only actions (firewall egress lock, deep eBPF/ETW mode) go
134
- through a small privileged helper — the guard itself needs no root.
84
+ In CI, use `--ci` for non-interactive behavior. If Sentrion blocks or needs a
85
+ decision, the command exits with status `87`.
135
86
 
136
87
  ## Policy
137
88
 
138
- Plain JSON, merged: built-in defaults → `~/.sentrion/policy.json` (you) →
139
- `./.sentrion.json` (project, committed). A project file may only make rules
140
- **stricter**, never looser, so a cloned repo can't ship a config that turns the
141
- guard off.
89
+ Sentrion reads policy from:
142
90
 
143
- ```jsonc
91
+ 1. Built-in defaults
92
+ 2. `~/.sentrion/policy.json`
93
+ 3. `./.sentrion.json`
94
+
95
+ Project policy can be stricter, but cannot disable protection.
96
+
97
+ ```json
144
98
  {
145
99
  "mode": "prompt",
146
- "install": { "allowHosts": ["registry.npmjs.org", "pypi.org"], "minPackageAgeHours": 48 },
147
- "secrets": { "paths": ["~/.ssh", "~/.aws", "~/.npmrc"], "stripEnv": ["NPM_TOKEN", "GITHUB_TOKEN"] },
148
- "rules": { "SCAN-02": "warn" },
149
- "trust": { "esbuild@^0.24": { "scripts": "allow", "spawn": ["node"] } }
100
+ "install": {
101
+ "allowHosts": ["registry.npmjs.org", "pypi.org"],
102
+ "minPackageAgeHours": 48
103
+ },
104
+ "rules": {
105
+ "SCAN-02": "warn"
106
+ }
150
107
  }
151
108
  ```
152
109
 
153
- Pressing **P** writes a narrow trust entry for that package, version range and
154
- behaviour; if a later version does something new, it no longer matches and
155
- Sentrion asks again — which is what defeats a hijacked update.
156
-
157
- ## Rules
158
-
159
- `SCAN-*` static pre-flight · `REPO-*` repo traps · `PROC-*` process behaviour ·
160
- `FILE-*` secret reads & dangerous writes · `PERS-*` persistence · `NET-*`
161
- network · `TOK-*` token abuse. Every incident names the exact rule that fired,
162
- so you can allow precisely that with `sentrion allow <rule>`.
163
-
164
- ## Verify it yourself
110
+ Create a project policy file:
165
111
 
166
112
  ```bash
167
- npm test # guard (9 assertions) + v0.3 subcommands (14 assertions)
168
- npm run eval # the full benchmark below, writes eval/results/
113
+ sentrion init
169
114
  ```
170
115
 
171
- `npm test` runs the guard against a benign script (must be **allowed**) and a
172
- **harmless** malware simulation (must be **blocked**). The simulation reads a
173
- canary file, aims one connection at a documentation-only IP (`203.0.113.7`), and
174
- tries `curl | sh`; it exfiltrates nothing and harms nothing.
175
-
176
- ## Evaluation
177
-
178
- `npm run eval` runs a labelled corpus of 16 behaviour scenarios — 9 malicious,
179
- 7 benign, across **Node and Python** — and reports the numbers to
180
- `eval/results/` (`results.json`, `results.csv`, `REPORT.md`).
116
+ ## Common Commands
181
117
 
182
- Latest run on Linux (Node 22):
118
+ ```bash
119
+ sentrion trust esbuild@^0.24
120
+ sentrion allow NET-02
121
+ sentrion update
122
+ sentrion policy show
123
+ sentrion shell-init
124
+ ```
183
125
 
184
- | metric | value |
185
- | --- | --- |
186
- | detection rate (malicious blocked) | **100%** (9/9) |
187
- | false-positive rate (benign blocked) | **0%** (0/7) |
188
- | correct-rule rate (right rule fired) | **100%** |
189
- | median guard overhead (benign) | **~55 ms** |
190
-
191
- This is a **synthetic** benchmark covering the rule classes with harmless
192
- simulations — not the real-malware corpus. Validating against the
193
- [DataDog malicious-software-packages dataset](https://github.com/DataDog/malicious-software-packages-dataset)
194
- and Backstabber's Knife Collection, plus macOS/Windows runs and a developer
195
- user-study, is the next step (see the architecture doc's evaluation plan).
196
-
197
- ## Limitations (base mode)
198
-
199
- Honest about what base mode buys you; see the architecture doc for the full
200
- matrix and the fix for each.
201
-
202
- - 100 ms process polling can miss a very short-lived native process; the Tier-1
203
- hook and deep mode close most of the gap.
204
- - Base mode runs as your user, so same-user malware could try to stop the guard;
205
- the fail-closed watchdog kills the group if the guard dies.
206
- - Windows has no portable process-suspend yet — it holds the *action*
207
- (network denied) while you decide.
208
- - `sentrion test` is a lightweight sandbox (enforce mode + a temporary HOME +
209
- the egress proxy), not a container; full filesystem/OS isolation is the
210
- privileged deep-mode path on the roadmap.
126
+ - `trust` approves a package and behavior narrowly.
127
+ - `allow` changes the behavior of a specific rule.
128
+ - `update` refreshes package security data.
129
+ - `policy show` prints the active policy.
130
+ - `shell-init` prints shell aliases for commands such as `npm`, `pip`, and
131
+ `python`.
211
132
 
212
133
  ## License
213
134
 
214
- MIT © 2026 imeerai
135
+ MIT License
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sentrion",
3
- "version": "1.0.0",
3
+ "version": "2.0.0",
4
4
  "description": "A live guard for developer machines: prefix any command (npm/pnpm/yarn/bun install, or running code in any language) with `sentrion` and it scans, watches and blocks malicious install scripts, credential theft, backdoors and privilege escalation — with a Kill/Allow prompt and a readable incident report.",
5
5
  "keywords": [
6
6
  "security",
@@ -11,7 +11,12 @@
11
11
  "sandbox",
12
12
  "postinstall",
13
13
  "egress",
14
- "devsecops"
14
+ "devsecops",
15
+ "cli",
16
+ "runtime-security",
17
+ "dependency-confusion",
18
+ "typosquat",
19
+ "incident-response"
15
20
  ],
16
21
  "homepage": "https://github.com/imeerai/sentrion#readme",
17
22
  "bugs": {