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.
- package/README.md +87 -166
- package/package.json +7 -2
package/README.md
CHANGED
|
@@ -1,214 +1,135 @@
|
|
|
1
1
|
# Sentrion
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
7
|
+
## Install
|
|
9
8
|
|
|
10
9
|
```bash
|
|
11
|
-
npm
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
20
|
+
Requires Node.js 18 or newer.
|
|
21
|
+
|
|
22
|
+
## Quick Start
|
|
57
23
|
|
|
58
24
|
```bash
|
|
59
|
-
|
|
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
|
-
#
|
|
37
|
+
# Package managers
|
|
66
38
|
sentrion npm install express
|
|
67
|
-
sentrion pnpm add zod
|
|
68
|
-
sentrion
|
|
69
|
-
sentrion
|
|
70
|
-
sentrion
|
|
71
|
-
|
|
72
|
-
#
|
|
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
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
sentrion
|
|
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
|
|
94
|
-
|
|
65
|
+
Every command supports `--json` for machine-readable output and `--quiet` for
|
|
66
|
+
minimal output.
|
|
95
67
|
|
|
96
|
-
|
|
68
|
+
## Modes
|
|
97
69
|
|
|
98
|
-
| Mode |
|
|
70
|
+
| Mode | Behavior |
|
|
99
71
|
| --- | --- |
|
|
100
|
-
| `prompt`
|
|
101
|
-
| `enforce` |
|
|
102
|
-
| `audit` |
|
|
103
|
-
| `learn` |
|
|
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
|
|
107
|
-
sentrion
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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": {
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
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
|
-
|
|
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
|
-
|
|
168
|
-
npm run eval # the full benchmark below, writes eval/results/
|
|
113
|
+
sentrion init
|
|
169
114
|
```
|
|
170
115
|
|
|
171
|
-
|
|
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
|
-
|
|
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
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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
|
|
135
|
+
MIT License
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sentrion",
|
|
3
|
-
"version": "
|
|
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": {
|