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 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
- # Temporary Holding Version
1
+ # Sentrion
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
@@ -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 };
@@ -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
+ };
@@ -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
+ };
@@ -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
+ };
@@ -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
+ }
@@ -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
+ }
@@ -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
+ };