@tuent/sentinel 0.1.0 → 0.1.1

package/README.md

@@ -1,19 +1,24 @@
 # @tuent/sentinel
 
-Runtime security for Claude Code. Sentinel evaluates a policy on every Claude Code tool call — before it runs — and records each decision to a hash-chained, signed audit trail.
+**Runtime security for Claude Code.** Sentinel checks your policy on every Claude Code tool call — _before_ it runs — and writes every decision to a signed, tamper-evident audit trail. Install it, point it at your project, and Claude Code operates inside guardrails you control.
 
-It is deliberately narrow. This is not a general-purpose "agent security platform"; it is a Claude-Code-native enforcement layer that hooks Claude Code's own tool-call lifecycle.
+Sentinel is purpose-built for Claude Code. Rather than loosely wrapping a general-purpose "agent platform," it hooks Claude Code's own tool-call lifecycle directly — enforcement happens at the exact point where the agent decides to act.
+
+## What you get
+
+- **Enforcement before execution** — every tool call is evaluated against your policy and allowed or denied before it runs, not flagged after the fact.
+- **A signed audit trail** — every decision appended to a hash-chained, Ed25519-signed trail anchored by a signed manifest, verifiable end to end.
+- **Automatic escalation** — repeated violations move the agent normal → restricted → quarantined at thresholds you set, and one command restores it.
+- **Behavioral baseline** — a per-workspace baseline surfaces deviation signals as advisory context.
 
 ## How it works
 
-`init` installs a hook into Claude Code's PreToolUse lifecycle. Each tool call is routed to a local gateway daemon, evaluated against your policy, and allowed or denied before execution. Every decision is appended to a signed, hash-chained audit trail.
+`init` installs a hook into Claude Code's PreToolUse lifecycle. Each tool call is routed to a local gateway daemon, evaluated against your policy, and allowed or denied before execution — then recorded to the signed trail.
 
 ```
 Claude Code tool call → PreToolUse hook → gateway daemon → policy decision → signed audit
 ```
 
-Enforcement is cooperative: it depends on Claude Code invoking the hook. Sentinel is not a sandbox and does not contain a hostile agent that bypasses the hook.
-
 ## Install
 
 ```sh
@@ -21,9 +26,7 @@ npm install @tuent/sentinel
 npx sentinel init claude-code
 ```
 
-`init` writes a `.sentinel.yaml` policy into your project, sets up the gateway hook, and merges a hook entry into `.claude/settings.local.json`. No `tsx` or build step is required — the gateway ships as a runnable daemon.
-
-Requires Node.js ≥ 20. ESM-only.
+`init` writes a `.sentinel.yaml` policy into your project, sets up the gateway hook, and merges a hook entry into `.claude/settings.local.json`. No build step — the gateway ships as a runnable daemon. Requires Node.js ≥ 20 (ESM-only).
 
 ## Policy
 
@@ -64,32 +67,25 @@ As policy violations accumulate, the agent escalates through modes: normal → r
 
 ## Audit trail
 
-Every decision is appended to a hash-chained trail and signed with Ed25519, anchored by a signed manifest. A verify check validates the hash chain and the entry signatures; the signed manifest anchors the chain.
+Every decision is appended to a hash-chained trail and signed with Ed25519, anchored by a signed manifest. Run `sentinel --verify-audit` to validate the chain and every entry signature.
 
-Scope and limits — please read:
+## Behavioral analytics
 
-- The trail is designed for a single writer (the gateway daemon). There is no inter-process write lock. Running concurrent writer processes against one trail can fork the chain, so a verify-audit failure can indicate benign concurrency rather than tampering.
-- Signature determinism currently relies on V8's JSON key ordering. Verifying on another engine (Bun, Deno) is not yet supported and may report false invalids.
-- The trail is stored in plaintext. It is tamper-evident, not tamper-proof: a compromised same-host process can alter it, and the signed manifest is designed to detect that, not prevent it.
+Sentinel maintains a per-workspace behavioral baseline and surfaces session-level deviation signals as advisory context. These are observational and do not block tool calls; the richer signals require a matured workspace baseline.
 
-## Behavioral analytics
+## If a tool call is unexpectedly blocked
 
-Sentinel maintains a per-workspace behavioral baseline and surfaces session-level, advisory deviation signals. These are observational; they do not block tool calls. Activity-absence can surface once a baseline exists; temporal, access-pattern, and the remaining deviation signals require a matured workspace baseline. None fire on a fresh install.
+Sentinel matches forbidden targets conservatively, which can occasionally deny a benign command that only _references_ a sensitive filename — for example, searching your code with `grep` for `.env`. Plain mentions under safe commands (`echo`, comments) pass through. If a false positive restricts or quarantines the agent, restore it in one step:
 
-## What Sentinel does not do
+```sh
+sentinel release
+```
 
-- It does not defend against prompt injection of the agent itself.
-- In log-adapter mode it does not block in real time (it observes, with latency).
-- It does not prevent log tampering by a compromised same-host process.
-- It does not detect encrypted or obfuscated exfiltration.
-- It does not defend against multi-agent coordinated activity.
-- It does not resolve symlinks in target paths.
-- Workspace identity is a non-cryptographic 32-bit hash. It distinguishes local workspaces; it is not collision-resistant.
+This records the change in the audit trail. Don't edit the mode state file by hand — that desyncs the trail from the live state.
 
-## Notes
+## Security model
 
-- Target and content matching is conservative and can produce false positives — for example, a literal token such as `process.env` can match a `.env` forbid pattern. Tune your policy accordingly.
-- On a cold start, the first tool call of a fresh session waits up to ~5 seconds for the daemon to warm up. If it is not ready, Sentinel applies its tiered fallback: high-sensitivity tools are denied, lower-sensitivity tools are allowed through.
+Sentinel's enforcement is **cooperative** — it works by intercepting Claude Code's tool-call hook — and the audit trail is **tamper-evident**, not tamper-proof. For the full threat model — what Sentinel defends against, what's out of scope by design, and current v0.1.0 limitations — see [SECURITY_MODEL.md](./SECURITY_MODEL.md).
 
 ## License
 

package/SECURITY_MODEL.md

@@ -0,0 +1,231 @@
+# Sentinel Security Model
+
+## What Sentinel Protects Against
+
+### Pre-Execution Enforcement
+
+When using `wrap()` or `wrapTool()`, Sentinel validates every action before the agent executes it. HIGH and CRITICAL severity actions are blocked -- the agent's execution function never runs. The dangerous file is never read, the unauthorized API is never called, the forbidden command is never executed.
+
+This is the strongest integration mode. The agent code passes its intended action and an execute function to Sentinel. If the action violates the role definition or targets a high-sensitivity resource, Sentinel returns `{ blocked: true }` and the execute function is never invoked. LOW and MEDIUM findings are informational -- the action still executes, and the finding is returned alongside the result for logging.
+
+### Role Violations
+
+Agents are bound to a defined set of allowed actions. If an agent with `allowedActions: ["file_read", "file_write"]` attempts a `command_exec` or `database_query`, Sentinel produces a **HIGH** `role_violation` finding immediately.
+
+### Unauthorized Target Access
+
+Targets are checked against glob patterns in two layers:
+
+1. **Forbidden patterns** (checked first) -- any match produces a **HIGH** `unauthorized_target`
+2. **Allowed patterns** (checked second) -- access outside allowed scope produces a **MEDIUM** `scope_violation`
+
+Pattern matching uses `**` (any path) and `*` (single segment). Examples:
+
+- `**/.env` matches `.env` at any depth
+- `**/.ssh/**` matches anything inside any `.ssh` directory
+- `src/**` matches all files under `src/`
+
+### Behavioral Anomalies
+
+After a baseline is computed from historical sessions, the DeviationDetector checks every new session for:
+
+- **Volume spikes** -- event count exceeds 3x the baseline average
+- **Unusual targets** -- more than 50% of accessed files are outside the agent's typical target set
+- **Weight anomaly** -- session engagement exceeds baseline normal range + 0.3 threshold
+- **Category shifts** -- activity type represents less than 5% of baseline behavior
+- **Activity drops** -- session event count drops 75%+ below baseline average (possible log suppression)
+- **Activity gaps** -- agent silence exceeds 2-3x the longest observed gap in the baseline period
+- **Convergence escalation** -- when 3+ MEDIUM findings occur in one session, the first is escalated to HIGH
+
+### High-Sensitivity Target Access
+
+The TargetSensitivityScorer assigns risk scores (0.0-1.0) to every target based on built-in pattern rules. Scores are multiplied by action type (writes are 1.3x, command execution is 1.5x). When the effective score reaches 0.9+, findings are escalated to **CRITICAL**.
+
+Built-in sensitivity categories:
+
+- **Credentials** (1.0): `.ssh/`, `.env`, `.aws/`, `secrets/`, `id_rsa*`, `.pem`, `shadow`
+- **System** (0.7-0.9): `/etc/`, `passwd`
+- **PII** (0.8-0.85): `users/`, `customers/`, `payments/`
+- **Database** (0.75-0.8): `database/`, `.sqlite`, `.db`
+- **Config** (0.5-0.75): `config/`, `config/production*`
+- **Source** (0.1-0.45): `src/`, `tests/`, `docs/`, `.git/`
+- **Default** (0.15): anything not matching a specific rule
+
+Custom rules can be injected via the `TargetSensitivityScorer` constructor, overriding built-in patterns.
+
+### Temporal Anomalies
+
+Agents can have an `expectedSchedule` with allowed days and hours (UTC). Activity outside the schedule produces a **MEDIUM** `temporal_anomaly`. The DeviationDetector independently checks against the baseline's typical active hours and days.
+
+### Path Traversal Attempts
+
+All target paths are normalized with `path.normalize()` before pattern matching. This resolves `../` and `./` sequences, preventing bypass attempts like:
+
+- `src/../.env` is normalized to `.env` before checking against `**/.env`
+- `project/subdir/../../.ssh/id_rsa` is normalized to `.ssh/id_rsa`
+
+---
+
+## What Sentinel Does NOT Protect Against
+
+### Prompt Injection
+
+Sentinel monitors agent **actions**, not agent **prompts**. It cannot detect or prevent prompt injection attacks directly. However, if a prompt injection causes an agent to perform a forbidden action (e.g., reading `.env`), that action **will** be caught by role validation.
+
+### Real-Time Blocking in Log Adapter Mode
+
+When using the LogAdapter (file-tailing mode), events are detected after they occur with a polling delay (default ~2 seconds). This mode is observation-only -- it cannot block actions.
+
+For real-time pre-execution enforcement, use one of:
+
+- **`sentinel.wrap()` / `sentinel.wrapTool()`** (recommended) -- synchronous enforcement, actions blocked before execution
+- **`sentinel.check()`** -- manual pre-execution gate in your agent orchestrator
+- **WebhookReceiver** in synchronous mode (agent sends event before executing)
+
+### Log Tampering by Compromised Agents
+
+If an AI agent and Sentinel run on the same host and the agent has write access to the filesystem, a compromised agent could theoretically modify its own log files or audit trail. **Mitigation:** Run Sentinel on a separate host and ingest events via the webhook adapter.
+
+### Encrypted or Obfuscated Data Exfiltration
+
+Sentinel sees which targets an agent accesses and what actions it performs. It does not inspect the content of data being read or transmitted. An agent reading a sensitive file and encoding its contents into an innocuous-looking API call would be partially detected (the file read is logged) but the exfiltration channel may not be flagged.
+
+### Multi-Agent Coordinated Attacks
+
+Each agent is monitored independently by default. The `CorrelationDetector` provides basic cross-agent pattern detection (e.g., read-then-exfiltrate chains), but sophisticated coordinated attacks where each agent stays within its own role may evade detection.
+
+### Symlink Resolution
+
+RoleValidator operates on path strings, not the filesystem. A symlink named `src/safe-link` pointing to `/etc/shadow` would pass the `src/**` allowed pattern check. Sentinel cannot resolve symlinks without filesystem access on the target host.
+
+### Concurrent Audit-Trail Writers (No Inter-Process Lock)
+
+The audit trail is designed for a **single writer** -- the gateway daemon. There is no inter-process write lock. Running concurrent writer processes against one trail can fork the hash chain, so a `verify-audit` failure can indicate benign concurrency rather than tampering.
+
+### Cross-Engine Signature Verification
+
+Ed25519 signature determinism currently relies on **V8's JSON key ordering** when serializing the signed payload. Verifying on another JavaScript engine (Bun, Deno) is not supported and may report false invalids.
+
+### Workspace Identity Collisions
+
+Workspace identity is a **32-bit FNV-1a hash** of the workspace root. It is non-cryptographic and not collision-resistant; it distinguishes local workspaces but is not a security boundary.
+
+### Conservative Matching / False Positives
+
+Target matching is deliberately conservative: a command that only _references_ a forbidden filename — for instance, a `grep` whose pattern or path is `.env` — can be denied even though it never opens the file. Because each denial counts toward the escalation ladder, a run of such false positives can move the agent to `restricted` or `quarantined`. Plain mentions under safe verbs (`echo`, `printf`) and in comments are not flagged. When a false positive does restrict or quarantine the agent, recover with `sentinel release`, which records the change in the audit trail. Tune policies to widen the allow set where this proves noisy.
+
+### Cold-Start Window
+
+On a cold start, the first tool call of a fresh session waits up to **~5 seconds** for the gateway daemon to warm up. If the daemon is not ready, the hook applies its **tiered fallback** rather than failing closed uniformly: high-sensitivity tools (e.g. `Bash`, `Write`, `Edit`, `WebFetch`) are **denied**, while lower-sensitivity tools (e.g. `Read`, `Glob`, `Grep`, `WebSearch`) are **allowed** through. MCP and unknown tools default to the high (deny) tier.
+
+---
+
+## Trust Model
+
+### Recommended Production Deployment
+
+```
++------------------+          HTTPS/webhook          +-------------------+
+|   AI Agent Host  |  -----------------------------> |  Sentinel Host    |
+|                  |     POST /api/sentinel/events   |                   |
+|  Agent runtime   |                                 |  WebhookReceiver  |
+|  sends events    |                                 |  RoleValidator    |
+|  before/after    |                                 |  AuditTrail       |
+|  each action     |                                 |  AlertManager     |
++------------------+                                 +-------------------+
+```
+
+- Sentinel runs on a separate host the agent cannot access
+- Events are pushed via authenticated webhook (API key in Authorization header)
+- Audit trail is on the Sentinel host, inaccessible to the agent
+- Alerts dispatch to external systems (Slack webhook, PagerDuty, etc.)
+
+### Development Deployment
+
+```
++----------------------------------------------+
+|               Same Host                      |
+|                                              |
+|  Agent runtime  --->  activity.log           |
+|                          |                   |
+|                    LogAdapter (polls)         |
+|                          |                   |
+|                    SentinelRunner             |
+|                    AuditTrail                 |
++----------------------------------------------+
+```
+
+- Sentinel watches the agent's log file via LogAdapter
+- Simpler setup but agent could tamper with its own logs
+- Suitable for development and testing
+
+### Audit Trail Integrity
+
+- Append-only: entries are only written, never modified or deleted programmatically
+- Per-agent: each agent has its own `audit.log` file
+- Rotation: files rotate at 10 MB, keeping 3 archives (audit.log.1, .2, .3)
+- All entries include timestamps and are queryable by time range and severity
+
+### Data Storage
+
+- All data is local to the Sentinel host filesystem
+- No cloud services, no external databases, no network dependencies
+- Storage location is configurable via `agentsDir` constructor parameter
+- Default: `~/.dahlia/agents/`
+
+---
+
+## Severity Levels
+
+| Severity     | Meaning                        | Triggers Alert?        | Response                                                                                                                              |
+| ------------ | ------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| **LOW**      | Notable but expected variation | No (unless configured) | Log for review. Weight anomalies, off-day activity.                                                                                   |
+| **MEDIUM**   | Warrants monitoring            | Configurable           | Single deviation signal. Volume spike, unusual targets, category shift, off-hours. Escalates to HIGH when 3+ converge in one session. |
+| **HIGH**     | Requires investigation         | Yes                    | Role violation, forbidden target access, escalated convergence.                                                                       |
+| **CRITICAL** | Immediate response required    | Yes                    | Target sensitivity effective score >= 0.9. Credential access, system file writes.                                                     |
+
+### Escalation Rules
+
+- MEDIUM findings escalate to HIGH when 3+ MEDIUM findings occur in a single session (convergence escalation)
+- HIGH findings are escalated to CRITICAL by the TargetSensitivityScorer when the effective score (sensitivity x action multiplier) reaches 0.9+
+
+---
+
+## Detection Capabilities
+
+| Threat                                        | Detection Method                             | Component                  | Expected Severity                             |
+| --------------------------------------------- | -------------------------------------------- | -------------------------- | --------------------------------------------- |
+| SSH key access (`~/.ssh/id_rsa`)              | Target sensitivity (1.0)                     | RoleValidator + Scorer     | CRITICAL                                      |
+| `.env` file read                              | Target sensitivity (1.0)                     | RoleValidator + Scorer     | CRITICAL                                      |
+| AWS credential access (`~/.aws/credentials`)  | Target sensitivity (1.0)                     | RoleValidator + Scorer     | CRITICAL                                      |
+| Kubernetes config access (`~/.kube/config`)   | Target sensitivity (0.95)                    | RoleValidator + Scorer     | CRITICAL                                      |
+| Write to `~/.ssh/authorized_keys` (backdoor)  | Target sensitivity (1.0 x 1.3 write)         | RoleValidator + Scorer     | CRITICAL                                      |
+| `/etc/passwd` read                            | Target sensitivity (0.9) + forbidden pattern | RoleValidator + Scorer     | CRITICAL                                      |
+| System config write (`/etc/nginx/nginx.conf`) | Target sensitivity (0.7 x 1.3 write = 0.91)  | RoleValidator + Scorer     | CRITICAL                                      |
+| Payment data access (`payments/`)             | Target sensitivity (0.85)                    | DeviationDetector + Scorer | HIGH                                          |
+| Database query by file-only agent             | Action not in allowedActions                 | RoleValidator              | HIGH                                          |
+| Shell command by code-writer agent            | Action not in allowedActions                 | RoleValidator              | HIGH                                          |
+| 3x baseline event volume                      | Event count exceeds threshold                | DeviationDetector          | MEDIUM (escalates to HIGH with other signals) |
+| >50% novel target files in session            | Target set comparison                        | DeviationDetector          | MEDIUM                                        |
+| Activity outside expected hours               | Schedule check (UTC)                         | RoleValidator              | MEDIUM                                        |
+| Weekend activity when weekday-only            | Schedule check (UTC)                         | RoleValidator              | MEDIUM                                        |
+| Path traversal (`src/../.env`)                | Path normalization + pattern match           | RoleValidator              | HIGH/CRITICAL (depends on target)             |
+| Category shift (rare action type)             | Baseline action distribution                 | DeviationDetector          | MEDIUM                                        |
+| Access outside allowed scope                  | Allowed target pattern miss                  | RoleValidator              | MEDIUM                                        |
+| Multiple converging anomalies (3+)            | Finding count in session                     | DeviationDetector          | MEDIUM escalated to HIGH                      |
+| Activity drop (75%+ fewer events)             | Event count vs baseline average              | DeviationDetector          | MEDIUM (HIGH at 90%+ drop)                    |
+| Extended agent silence (2-3x max gap)         | Time since last event vs baseline gaps       | DeviationDetector          | LOW (MEDIUM at 3x+)                           |
+
+---
+
+## Finding Types
+
+| Type                  | Source                           | Description                                                                               |
+| --------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
+| `role_violation`      | RoleValidator                    | Agent performed an action not in its `allowedActions` list                                |
+| `unauthorized_target` | RoleValidator, DeviationDetector | Agent accessed a target matching `forbiddenTargetPatterns` or scoring high on sensitivity |
+| `scope_violation`     | RoleValidator                    | Agent accessed a target outside its `allowedTargetPatterns`                               |
+| `temporal_anomaly`    | RoleValidator, DeviationDetector | Activity outside expected schedule or baseline typical hours/days                         |
+| `volume_spike`        | DeviationDetector                | Session event count exceeds baseline average by 3x+                                       |
+| `access_pattern`      | DeviationDetector                | Unusual target distribution, weight anomaly, or category shift                            |
+| `behavioral_absence`  | DeviationDetector                | Significant activity drop (75%+ below baseline) or extended silence (2-3x max gap)        |

package/dist/Sentinel-QHMQ67W3.js

@@ -0,0 +1,10 @@
+import {
+  Sentinel
+} from "./chunk-NS6ZLMDK.js";
+import "./chunk-QHE56MEO.js";
+import "./chunk-2FFMYSVC.js";
+import "./chunk-NUXSUSYY.js";
+export {
+  Sentinel
+};
+//# sourceMappingURL=Sentinel-QHMQ67W3.js.map

package/dist/chunk-B5QKJHSV.js

@@ -0,0 +1,32 @@
+// src/workspaceIdentity.ts
+var AGENT_PREFIX = "claude-code";
+function fnv1a32Hex(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+function lastSegment(path) {
+  const parts = path.split("/").filter(Boolean);
+  return parts.length > 0 ? parts[parts.length - 1] : "";
+}
+function slugify(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+function normalizeRoot(root) {
+  if (root === "" || root === "/") return root;
+  return root.replace(/\/+$/, "") || "/";
+}
+function deriveAgentId(workspaceRoot) {
+  const root = normalizeRoot(workspaceRoot);
+  const slug = slugify(lastSegment(root)) || "root";
+  const hash = fnv1a32Hex(root);
+  return `${AGENT_PREFIX}@${slug}-${hash}`;
+}
+
+export {
+  deriveAgentId
+};
+//# sourceMappingURL=chunk-B5QKJHSV.js.map