sentrion 0.0.0-stage → 1.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/LICENSE +21 -0
- package/README.md +213 -2
- package/bin/sentrion.js +11 -0
- package/lib/cli.js +117 -0
- package/lib/cmd-allow.js +16 -0
- package/lib/cmd-doctor.js +40 -0
- package/lib/cmd-init.js +26 -0
- package/lib/cmd-mode.js +22 -0
- package/lib/cmd-rules.js +51 -0
- package/lib/cmd-scan.js +58 -0
- package/lib/cmd-shell-init.js +28 -0
- package/lib/cmd-test.js +26 -0
- package/lib/cmd-trust.js +53 -0
- package/lib/cmd-update.js +59 -0
- package/lib/data/malware.json +56 -0
- package/lib/data/typosquats.json +13 -0
- package/lib/guard.js +246 -0
- package/lib/hook.js +257 -0
- package/lib/policy.js +109 -0
- package/lib/proxy.js +61 -0
- package/lib/py/sitecustomize.py +167 -0
- package/lib/report.js +131 -0
- package/lib/rules.js +43 -0
- package/lib/scan.js +131 -0
- package/lib/sensors.js +112 -0
- package/lib/store.js +32 -0
- package/lib/ui.js +63 -0
- package/package.json +38 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 imeerai — imeer.ai
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,214 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Sentrion
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
7
|
+
|
|
8
|
+
> One engine. Linux, macOS and Windows. Zero npm dependencies.
|
|
9
|
+
|
|
10
|
+
```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
|
|
16
|
+
```
|
|
17
|
+
|
|
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
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npm install -g sentrion
|
|
52
|
+
sentrion --help
|
|
53
|
+
sentrion doctor # what this OS lets Sentrion see and block
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Use it every time by adding shell aliases:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
eval "$(sentrion shell-init)" # npm -> sentrion npm, pip -> sentrion pip, ...
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Usage
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
# guard any command
|
|
66
|
+
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
|
|
73
|
+
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
|
|
90
|
+
sentrion doctor
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Every command accepts `--json` (machine-readable, for CI) and `--quiet`
|
|
94
|
+
(only blocks and prompts show).
|
|
95
|
+
|
|
96
|
+
### Modes
|
|
97
|
+
|
|
98
|
+
| Mode | On a risky event |
|
|
99
|
+
| --- | --- |
|
|
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 |
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
sentrion --mode audit npm install some-pkg
|
|
107
|
+
sentrion --ci npm install # non-interactive; any ask/block = exit 87
|
|
108
|
+
```
|
|
109
|
+
|
|
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.
|
|
135
|
+
|
|
136
|
+
## Policy
|
|
137
|
+
|
|
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.
|
|
142
|
+
|
|
143
|
+
```jsonc
|
|
144
|
+
{
|
|
145
|
+
"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"] } }
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
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
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
npm test # guard (9 assertions) + v0.3 subcommands (14 assertions)
|
|
168
|
+
npm run eval # the full benchmark below, writes eval/results/
|
|
169
|
+
```
|
|
170
|
+
|
|
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`).
|
|
181
|
+
|
|
182
|
+
Latest run on Linux (Node 22):
|
|
183
|
+
|
|
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.
|
|
211
|
+
|
|
212
|
+
## License
|
|
213
|
+
|
|
214
|
+
MIT © 2026 imeerai
|
package/bin/sentrion.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
'use strict';
|
|
3
|
+
// Sentrion CLI entry. by imeerai — MIT.
|
|
4
|
+
const { main } = require('../lib/cli.js');
|
|
5
|
+
|
|
6
|
+
main(process.argv)
|
|
7
|
+
.then((code) => process.exit(typeof code === 'number' ? code : 0))
|
|
8
|
+
.catch((err) => {
|
|
9
|
+
console.error('sentrion: ' + (err && err.message ? err.message : err));
|
|
10
|
+
process.exit(1);
|
|
11
|
+
});
|
package/lib/cli.js
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
const path = require('path');
|
|
3
|
+
const { c, tag } = require('./ui.js');
|
|
4
|
+
const pkg = require('../package.json');
|
|
5
|
+
|
|
6
|
+
const HELP = `
|
|
7
|
+
${tag()} v${pkg.version} a live guard for developer machines
|
|
8
|
+
|
|
9
|
+
${c.bold('USAGE')}
|
|
10
|
+
sentrion <command> [args...] run any command under the guard
|
|
11
|
+
sentrion <subcommand> [options]
|
|
12
|
+
|
|
13
|
+
${c.bold('GUARD ANY COMMAND')} ${c.dim('(scan, watch, decide, live)')}
|
|
14
|
+
sentrion npm install express guard a package install
|
|
15
|
+
sentrion pnpm add zod also yarn, bun, npx, pnpx, bunx
|
|
16
|
+
sentrion pip install requests also uv, poetry, pipx
|
|
17
|
+
sentrion python3 app.py the fake-interview case
|
|
18
|
+
sentrion node server.js
|
|
19
|
+
sentrion run -- <cmd...> explicit form (use after flags)
|
|
20
|
+
|
|
21
|
+
${c.bold('INSPECT BEFORE RUNNING')}
|
|
22
|
+
sentrion scan <package[@version]> static check of a package, nothing runs
|
|
23
|
+
sentrion scan . static check of this repo/clone
|
|
24
|
+
sentrion test -- <cmd...> run in a throwaway sandbox (enforce + temp home)
|
|
25
|
+
|
|
26
|
+
${c.bold('DECISIONS & EVIDENCE')}
|
|
27
|
+
sentrion report [--last|<id>|--all] what happened and why it was blocked
|
|
28
|
+
sentrion report <id> --format sarif export for CI code scanning (also --json)
|
|
29
|
+
sentrion rules [<id>] list the rule set, or show one rule
|
|
30
|
+
sentrion policy [show|path] the effective, merged policy
|
|
31
|
+
|
|
32
|
+
${c.bold('TRUST & SETUP')}
|
|
33
|
+
sentrion trust <pkg[@range]> allow one package's scripts (narrow, pinned)
|
|
34
|
+
sentrion untrust <pkg> remove a trust entry
|
|
35
|
+
sentrion allow <RULE-ID> set one rule to allow in your policy
|
|
36
|
+
sentrion mode <prompt|enforce|audit|learn> set your default mode
|
|
37
|
+
sentrion init scaffold ./.sentrion.json for a repo
|
|
38
|
+
sentrion update refresh the malware + typosquat lists
|
|
39
|
+
sentrion shell-init [bash|zsh|pwsh] print aliases (npm -> sentrion npm ...)
|
|
40
|
+
sentrion doctor what this OS lets Sentrion see and block
|
|
41
|
+
|
|
42
|
+
${c.bold('OPTIONS')}
|
|
43
|
+
--mode <prompt|enforce|audit|learn> override the policy mode for this run
|
|
44
|
+
--ci non-interactive; any ask/block = fail
|
|
45
|
+
--json machine-readable output (report, rules, scan)
|
|
46
|
+
--quiet, -q silence normal output; only blocks/prompts
|
|
47
|
+
--no-color plain output
|
|
48
|
+
-h, --help this help
|
|
49
|
+
-v, --version version and platform
|
|
50
|
+
|
|
51
|
+
${c.bold('MODES')}
|
|
52
|
+
prompt pause on a risky event and ask: K kill / A allow once / P trust (default)
|
|
53
|
+
enforce block per policy, never ask (servers, CI, --ci)
|
|
54
|
+
audit log only, block nothing (first week, tuning)
|
|
55
|
+
learn record what each package normally does and propose allow rules
|
|
56
|
+
|
|
57
|
+
docs: https://github.com/imeerai/sentrion license: MIT by imeerai
|
|
58
|
+
`;
|
|
59
|
+
|
|
60
|
+
function parseFlags(args) {
|
|
61
|
+
const opts = {}; const rest = [];
|
|
62
|
+
for (let i = 0; i < args.length; i++) {
|
|
63
|
+
const a = args[i];
|
|
64
|
+
if (a === '--mode') opts.mode = args[++i];
|
|
65
|
+
else if (a === '--ci') opts.ci = true;
|
|
66
|
+
else if (a === '--json') opts.json = true;
|
|
67
|
+
else if (a === '--quiet' || a === '-q') opts.quiet = true;
|
|
68
|
+
else if (a === '--no-color') process.env.NO_COLOR = '1';
|
|
69
|
+
else if (a === '--format') opts.format = args[++i];
|
|
70
|
+
else if (a === '--last') rest.push('--last');
|
|
71
|
+
else if (a === '--all') rest.push('--all');
|
|
72
|
+
else rest.push(a);
|
|
73
|
+
}
|
|
74
|
+
return { opts, rest };
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
async function main(argv) {
|
|
78
|
+
const raw = argv.slice(2);
|
|
79
|
+
if (!raw.length || raw[0] === '-h' || raw[0] === '--help') { console.log(HELP); return 0; }
|
|
80
|
+
if (raw[0] === '-v' || raw[0] === '--version') {
|
|
81
|
+
console.log(`sentrion ${pkg.version} · ${process.platform}-${process.arch}`);
|
|
82
|
+
return 0;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
const { opts, rest } = parseFlags(raw);
|
|
86
|
+
const sub = rest[0];
|
|
87
|
+
|
|
88
|
+
if (sub === 'scan') return require('./cmd-scan.js')(rest.slice(1), opts);
|
|
89
|
+
if (sub === 'report') return require('./report.js').show(rest[1], opts) || 0;
|
|
90
|
+
if (sub === 'rules') return require('./cmd-rules.js')(rest.slice(1), opts);
|
|
91
|
+
if (sub === 'trust') return require('./cmd-trust.js').trust(rest.slice(1), opts);
|
|
92
|
+
if (sub === 'untrust') return require('./cmd-trust.js').untrust(rest.slice(1), opts);
|
|
93
|
+
if (sub === 'allow') return require('./cmd-allow.js')(rest.slice(1), opts);
|
|
94
|
+
if (sub === 'mode') return require('./cmd-mode.js')(rest.slice(1), opts);
|
|
95
|
+
if (sub === 'init') return require('./cmd-init.js')(rest.slice(1), opts);
|
|
96
|
+
if (sub === 'update') return require('./cmd-update.js')(opts);
|
|
97
|
+
if (sub === 'test') return require('./cmd-test.js')(rest.slice(1), opts);
|
|
98
|
+
if (sub === 'policy') {
|
|
99
|
+
const p = require('./policy.js').load(opts);
|
|
100
|
+
if (rest[1] === 'path') console.log(path.join(require('os').homedir(), '.sentrion', 'policy.json'));
|
|
101
|
+
else console.log(JSON.stringify(p, null, 2));
|
|
102
|
+
return 0;
|
|
103
|
+
}
|
|
104
|
+
if (sub === 'doctor') return require('./cmd-doctor.js')();
|
|
105
|
+
if (sub === 'shell-init') return require('./cmd-shell-init.js')(rest[1]);
|
|
106
|
+
|
|
107
|
+
// otherwise: guard a command. "run -- cmd" or "npm install ..." etc.
|
|
108
|
+
let cmd = rest;
|
|
109
|
+
if (sub === 'run') {
|
|
110
|
+
const dd = rest.indexOf('--');
|
|
111
|
+
cmd = dd >= 0 ? rest.slice(dd + 1) : rest.slice(1);
|
|
112
|
+
}
|
|
113
|
+
if (!cmd.length) { console.error('sentrion: nothing to run. See sentrion --help'); return 2; }
|
|
114
|
+
return require('./guard.js').run(cmd, opts);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
module.exports = { main, HELP };
|
package/lib/cmd-allow.js
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
// `sentrion allow <RULE-ID>` — set a rule's action to "allow" in your user policy
|
|
3
|
+
// (the precise counterpart to an incident that names the exact rule that fired).
|
|
4
|
+
const store = require('./store.js');
|
|
5
|
+
const { RULES } = require('./rules.js');
|
|
6
|
+
const { c, tag } = require('./ui.js');
|
|
7
|
+
|
|
8
|
+
module.exports = function allow(args) {
|
|
9
|
+
const id = (args[0] || '').toUpperCase();
|
|
10
|
+
if (!id) { console.error('sentrion allow: give a rule id, e.g. sentrion allow NET-02'); return 2; }
|
|
11
|
+
if (!RULES[id]) { console.error(`sentrion allow: no rule "${id}". Run sentrion rules for the list.`); return 2; }
|
|
12
|
+
const f = store.update((o) => { o.rules = o.rules || {}; o.rules[id] = 'allow'; });
|
|
13
|
+
console.log(`\n ${tag()} ${c.green('allow')} · ${c.white(id)} ${RULES[id].title} — set to allow (user policy)`);
|
|
14
|
+
console.log(c.dim(` ${f} · undo by removing it from "rules"\n`));
|
|
15
|
+
return 0;
|
|
16
|
+
};
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
const cp = require('child_process');
|
|
3
|
+
const { c, tag } = require('./ui.js');
|
|
4
|
+
|
|
5
|
+
function has(bin, args = ['--version']) {
|
|
6
|
+
try { cp.execFileSync(bin, args, { stdio: 'ignore', timeout: 4000 }); return true; }
|
|
7
|
+
catch { return false; }
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
module.exports = function doctor() {
|
|
11
|
+
const p = process.platform;
|
|
12
|
+
process.stdout.write(`\n ${tag()} ${c.dim('doctor — what this machine lets Sentrion see and block')}\n\n`);
|
|
13
|
+
const rows = [];
|
|
14
|
+
rows.push(['platform', p]);
|
|
15
|
+
rows.push(['node', process.version]);
|
|
16
|
+
rows.push(['Tier-1 Node hook', c.green('yes') + c.dim(' (always available)')]);
|
|
17
|
+
|
|
18
|
+
if (p === 'linux') {
|
|
19
|
+
rows.push(['process tree', '/proc ' + c.green('yes')]);
|
|
20
|
+
rows.push(['kill tree', 'process groups ' + c.green('yes')]);
|
|
21
|
+
rows.push(['pause tree', 'SIGSTOP ' + c.green('yes')]);
|
|
22
|
+
rows.push(['egress lock', 'nft ' + (has('nft', ['-v']) ? c.green('yes (root)') : c.yellow('needs nft + root'))]);
|
|
23
|
+
rows.push(['deep mode', 'eBPF/auditd ' + c.dim('optional, root')]);
|
|
24
|
+
} else if (p === 'darwin') {
|
|
25
|
+
rows.push(['process tree', 'ps ' + (has('ps', ['-V']) || has('ps', []) ? c.green('yes') : c.yellow('no'))]);
|
|
26
|
+
rows.push(['kill tree', 'process groups ' + c.green('yes')]);
|
|
27
|
+
rows.push(['pause tree', 'SIGSTOP ' + c.green('yes')]);
|
|
28
|
+
rows.push(['egress lock', 'pf ' + c.yellow('needs root')]);
|
|
29
|
+
rows.push(['confine', 'sandbox-exec ' + (has('sandbox-exec', []) ? c.green('yes') : c.yellow('no'))]);
|
|
30
|
+
} else if (p === 'win32') {
|
|
31
|
+
rows.push(['process tree', 'Win32_Process ' + (has('powershell', ['-Command', '$PSVersionTable.PSVersion']) ? c.green('yes') : c.yellow('no'))]);
|
|
32
|
+
rows.push(['kill tree', 'taskkill /T ' + c.green('yes')]);
|
|
33
|
+
rows.push(['pause tree', c.yellow('held at source (no suspend in v0.1)')]);
|
|
34
|
+
rows.push(['egress lock', 'Windows Firewall ' + c.yellow('needs admin')]);
|
|
35
|
+
}
|
|
36
|
+
const w = Math.max(...rows.map((r) => r[0].length));
|
|
37
|
+
for (const [k, v] of rows) process.stdout.write(` ${k.padEnd(w)} ${v}\n`);
|
|
38
|
+
process.stdout.write(`\n ${c.dim('base mode needs no root; egress lock and deep mode use the privileged helper')}\n\n`);
|
|
39
|
+
return 0;
|
|
40
|
+
};
|
package/lib/cmd-init.js
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
// `sentrion init` — scaffold ./.sentrion.json so a repo carries its own mode and
|
|
3
|
+
// allow list. A project file may only make the guard STRICTER, never looser.
|
|
4
|
+
const fs = require('fs');
|
|
5
|
+
const path = require('path');
|
|
6
|
+
const { c, tag } = require('./ui.js');
|
|
7
|
+
|
|
8
|
+
const TEMPLATE = {
|
|
9
|
+
$schema: 'https://github.com/imeerai/sentrion#project-policy',
|
|
10
|
+
mode: 'prompt',
|
|
11
|
+
install: { allowHosts: [], minPackageAgeHours: 48 },
|
|
12
|
+
rules: {},
|
|
13
|
+
trust: {},
|
|
14
|
+
};
|
|
15
|
+
|
|
16
|
+
module.exports = function init(args) {
|
|
17
|
+
const file = path.join(process.cwd(), '.sentrion.json');
|
|
18
|
+
if (fs.existsSync(file) && !args.includes('--force')) {
|
|
19
|
+
console.error(`sentrion init: ${file} already exists. Use sentrion init --force to overwrite.`);
|
|
20
|
+
return 1;
|
|
21
|
+
}
|
|
22
|
+
fs.writeFileSync(file, JSON.stringify(TEMPLATE, null, 2) + '\n');
|
|
23
|
+
console.log(`\n ${tag()} ${c.green('created')} ./.sentrion.json`);
|
|
24
|
+
console.log(c.dim(' commit it so everyone who clones this repo gets the same guard.\n'));
|
|
25
|
+
return 0;
|
|
26
|
+
};
|
package/lib/cmd-mode.js
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
// `sentrion mode <name>` — set the default mode in ~/.sentrion/policy.json.
|
|
3
|
+
const store = require('./store.js');
|
|
4
|
+
const { c, tag } = require('./ui.js');
|
|
5
|
+
|
|
6
|
+
const MODES = ['prompt', 'enforce', 'audit', 'learn'];
|
|
7
|
+
|
|
8
|
+
module.exports = function mode(args) {
|
|
9
|
+
const m = (args[0] || '').toLowerCase();
|
|
10
|
+
if (!m) { // show current
|
|
11
|
+
const cur = store.read().mode || 'prompt';
|
|
12
|
+
console.log(`${tag()} default mode = ${c.white(cur)} ${c.dim('(' + store.file() + ')')}`);
|
|
13
|
+
return 0;
|
|
14
|
+
}
|
|
15
|
+
if (!MODES.includes(m)) {
|
|
16
|
+
console.error('sentrion mode: choose one of ' + MODES.join(', '));
|
|
17
|
+
return 2;
|
|
18
|
+
}
|
|
19
|
+
const f = store.update((o) => { o.mode = m; });
|
|
20
|
+
console.log(`${tag()} default mode = ${c.white(m)} ${c.dim('(' + f + ')')}`);
|
|
21
|
+
return 0;
|
|
22
|
+
};
|
package/lib/cmd-rules.js
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
// `sentrion rules` — list every rule and its default action
|
|
3
|
+
// `sentrion rules NET-01` — show one rule in detail
|
|
4
|
+
// `sentrion rules --json` — machine-readable
|
|
5
|
+
const { RULES } = require('./rules.js');
|
|
6
|
+
const { c, tag, sev } = require('./ui.js');
|
|
7
|
+
|
|
8
|
+
const ACT = { block: c.red, ask: c.yellow, warn: c.dim, allow: c.green };
|
|
9
|
+
|
|
10
|
+
module.exports = function rules(args, opts = {}) {
|
|
11
|
+
const want = (args[0] || '').toUpperCase();
|
|
12
|
+
|
|
13
|
+
if (want && RULES[want]) {
|
|
14
|
+
const r = RULES[want];
|
|
15
|
+
if (opts.json) { console.log(JSON.stringify({ id: want, ...r }, null, 2)); return 0; }
|
|
16
|
+
console.log(`\n ${tag()} ${(sev[r.sev] || c.yellow)(want)} ${r.title}`);
|
|
17
|
+
console.log(` severity ${r.sev}`);
|
|
18
|
+
console.log(` install ${(ACT[r.install] || c.dim)(r.install)}`);
|
|
19
|
+
console.log(` run ${(ACT[r.run] || c.dim)(r.run)}\n`);
|
|
20
|
+
return 0;
|
|
21
|
+
}
|
|
22
|
+
if (want) { console.error(`sentrion rules: no rule "${want}". Run sentrion rules for the list.`); return 2; }
|
|
23
|
+
|
|
24
|
+
const ids = Object.keys(RULES);
|
|
25
|
+
if (opts.json) { console.log(JSON.stringify(RULES, null, 2)); return 0; }
|
|
26
|
+
|
|
27
|
+
const tally = { block: 0, ask: 0, warn: 0, allow: 0 };
|
|
28
|
+
for (const id of ids) tally[RULES[id].install] = (tally[RULES[id].install] || 0) + 1;
|
|
29
|
+
|
|
30
|
+
process.stdout.write(`\n ${tag()} ${c.dim('rule set — default action shown per phase (install / run)')}\n\n`);
|
|
31
|
+
let group = '';
|
|
32
|
+
for (const id of ids) {
|
|
33
|
+
const g = id.split('-')[0];
|
|
34
|
+
if (g !== group) { group = g; process.stdout.write(` ${c.dim(groupName(g))}\n`); }
|
|
35
|
+
const r = RULES[id];
|
|
36
|
+
const col = sev[r.sev] || c.yellow;
|
|
37
|
+
process.stdout.write(` ${col(id.padEnd(9))} ${r.title.padEnd(52)} ${(ACT[r.install] || c.dim)(r.install)}${c.dim(' / ')}${(ACT[r.run] || c.dim)(r.run)}\n`);
|
|
38
|
+
}
|
|
39
|
+
process.stdout.write(`\n ${ids.length} rules · ${tally.block} block · ${tally.ask} ask · ${tally.warn} warn · ${tally.allow || 0} allow ${c.dim('(by install default)')}\n`);
|
|
40
|
+
process.stdout.write(c.dim(` sentrion rules <ID> for one rule · override in policy with "rules": { "${ids[0]}": "warn" }\n\n`));
|
|
41
|
+
return 0;
|
|
42
|
+
};
|
|
43
|
+
|
|
44
|
+
function groupName(g) {
|
|
45
|
+
return ({
|
|
46
|
+
SCAN: 'SCAN · static pre-flight', REPO: 'REPO · repository traps',
|
|
47
|
+
PROC: 'PROC · process behaviour', PERS: 'PERS · persistence',
|
|
48
|
+
FILE: 'FILE · secret reads & dangerous writes', NET: 'NET · network',
|
|
49
|
+
TOK: 'TOK · token abuse',
|
|
50
|
+
})[g] || g;
|
|
51
|
+
}
|
package/lib/cmd-scan.js
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
const fs = require('fs');
|
|
3
|
+
const { scanRepo, scanName } = require('./scan.js');
|
|
4
|
+
const { load } = require('./policy.js');
|
|
5
|
+
const { c, tag, sev } = require('./ui.js');
|
|
6
|
+
const { baseAction } = require('./rules.js');
|
|
7
|
+
|
|
8
|
+
module.exports = function scanCmd(args, opts) {
|
|
9
|
+
const target = args[0];
|
|
10
|
+
if (!target) { console.error('sentrion scan: give a package name or a path. e.g. sentrion scan .'); return 2; }
|
|
11
|
+
const policy = load(opts);
|
|
12
|
+
|
|
13
|
+
let findings; let kind;
|
|
14
|
+
const asPath = target === '.' || target.startsWith('.') || target.startsWith('/') || fs.existsSync(target);
|
|
15
|
+
if (asPath) { findings = scanRepo(target); kind = 'repo'; }
|
|
16
|
+
else { findings = scanName(target, policy); kind = 'package'; }
|
|
17
|
+
|
|
18
|
+
if (opts.json) {
|
|
19
|
+
const out = findings.map((f) => ({
|
|
20
|
+
rule: f.rule, title: f.title, sev: f.sev,
|
|
21
|
+
action: f.rule === 'INFO' ? 'warn' : baseAction(f.rule, kind === 'repo' ? 'run' : 'install'),
|
|
22
|
+
detail: f.detail || null,
|
|
23
|
+
}));
|
|
24
|
+
const block = out.filter((o) => o.action === 'block').length;
|
|
25
|
+
const ask = out.filter((o) => o.action === 'ask').length;
|
|
26
|
+
console.log(JSON.stringify({
|
|
27
|
+
target, kind, verdict: block ? 'high-risk' : ask ? 'review' : 'ok',
|
|
28
|
+
counts: { block, ask, note: out.length - block - ask }, findings: out,
|
|
29
|
+
}, null, 2));
|
|
30
|
+
return block ? 87 : 0;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
process.stdout.write(`\n ${tag()} ${c.dim('scan only — nothing will run')}\n\n`);
|
|
34
|
+
process.stdout.write(` ${kind === 'repo' ? 'repo ' : 'package'} ${c.white(target)}\n\n`);
|
|
35
|
+
|
|
36
|
+
let block = 0, ask = 0, warn = 0;
|
|
37
|
+
if (!findings.length) {
|
|
38
|
+
process.stdout.write(` ${c.green('✓')} no risky patterns found\n`);
|
|
39
|
+
}
|
|
40
|
+
for (const f of findings) {
|
|
41
|
+
const act = f.rule === 'INFO' ? 'warn' : baseAction(f.rule, kind === 'repo' ? 'run' : 'install');
|
|
42
|
+
const mark = act === 'block' ? c.red('✕') : act === 'ask' ? c.yellow('!') : c.dim('·');
|
|
43
|
+
if (act === 'block') block++; else if (act === 'ask') ask++; else warn++;
|
|
44
|
+
const col = sev[f.sev] || c.dim;
|
|
45
|
+
const d = f.detail ? c.dim(' ' + JSON.stringify(f.detail).slice(0, 70)) : '';
|
|
46
|
+
process.stdout.write(` ${mark} ${col((f.rule || '').padEnd(8))} ${f.title}${d}\n`);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
const verdict = block ? c.redBg(' HIGH RISK ') : ask ? c.yellow(' REVIEW ') : c.green(' LOOKS OK ');
|
|
50
|
+
process.stdout.write(`\n verdict ${verdict} ${block} block ${ask} ask ${warn} note\n`);
|
|
51
|
+
if (block || ask) {
|
|
52
|
+
process.stdout.write(`\n ${c.bold('Do not run this directly.')}\n`);
|
|
53
|
+
process.stdout.write(` ${c.cyan('sentrion test -- <cmd>')} run it in a throwaway sandbox first\n`);
|
|
54
|
+
process.stdout.write(` ${c.cyan('sentrion <cmd>')} or run it guarded (secrets hidden, egress via proxy)\n`);
|
|
55
|
+
}
|
|
56
|
+
process.stdout.write('\n');
|
|
57
|
+
return block ? 87 : 0;
|
|
58
|
+
};
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
const { c } = require('./ui.js');
|
|
3
|
+
|
|
4
|
+
const MANAGERS = ['npm', 'pnpm', 'yarn', 'bun', 'npx', 'pnpx', 'bunx', 'pip', 'pip3', 'uv', 'poetry'];
|
|
5
|
+
|
|
6
|
+
module.exports = function shellInit(shell) {
|
|
7
|
+
const sh = (shell || detect()).toLowerCase();
|
|
8
|
+
const lines = [];
|
|
9
|
+
if (sh === 'pwsh' || sh === 'powershell') {
|
|
10
|
+
for (const m of MANAGERS) lines.push(`function ${m} { sentrion ${m} @args }`);
|
|
11
|
+
} else {
|
|
12
|
+
for (const m of MANAGERS) lines.push(`alias ${m}='sentrion ${m}'`);
|
|
13
|
+
}
|
|
14
|
+
// header as comments so `eval "$(sentrion shell-init)"` is safe
|
|
15
|
+
const cmt = (sh === 'pwsh' || sh === 'powershell') ? '#' : '#';
|
|
16
|
+
process.stdout.write(`${cmt} Sentrion shell integration (${sh}). Add to your shell rc, or:\n`);
|
|
17
|
+
process.stdout.write(`${cmt} eval "$(sentrion shell-init)"\n`);
|
|
18
|
+
process.stdout.write(lines.join('\n') + '\n');
|
|
19
|
+
return 0;
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
function detect() {
|
|
23
|
+
const s = process.env.SHELL || '';
|
|
24
|
+
if (s.includes('zsh')) return 'zsh';
|
|
25
|
+
if (s.includes('bash')) return 'bash';
|
|
26
|
+
if (process.platform === 'win32') return 'pwsh';
|
|
27
|
+
return 'bash';
|
|
28
|
+
}
|
package/lib/cmd-test.js
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
// `sentrion test -- <cmd>` — run a command in a throwaway sandbox before you
|
|
3
|
+
// trust it: the guard runs in ENFORCE mode (every risky action blocked, no
|
|
4
|
+
// prompts) inside a temporary HOME and working directory, so writes never touch
|
|
5
|
+
// your project and secret-path reads land in an empty home. Lightweight, not a
|
|
6
|
+
// container: full OS isolation is the privileged/deep-mode path.
|
|
7
|
+
|
|
8
|
+
const fs = require('fs');
|
|
9
|
+
const os = require('os');
|
|
10
|
+
const path = require('path');
|
|
11
|
+
const { c, tag } = require('./ui.js');
|
|
12
|
+
|
|
13
|
+
module.exports = async function test(args, opts = {}) {
|
|
14
|
+
const dd = args.indexOf('--');
|
|
15
|
+
const cmd = dd >= 0 ? args.slice(dd + 1) : args;
|
|
16
|
+
if (!cmd.length) { console.error('sentrion test: nothing to run. e.g. sentrion test -- node app.js'); return 2; }
|
|
17
|
+
|
|
18
|
+
const box = fs.mkdtempSync(path.join(os.tmpdir(), 'sentrion-box-'));
|
|
19
|
+
process.stdout.write(`\n ${tag()} ${c.dim('test — throwaway sandbox (enforce mode · temp HOME & CWD · egress via proxy)')}\n`);
|
|
20
|
+
process.stdout.write(c.dim(` box ${box}\n`));
|
|
21
|
+
try {
|
|
22
|
+
return await require('./guard.js').run(cmd, { ...opts, mode: 'enforce', sandbox: box });
|
|
23
|
+
} finally {
|
|
24
|
+
try { fs.rmSync(box, { recursive: true, force: true }); } catch {}
|
|
25
|
+
}
|
|
26
|
+
};
|