Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ on:
workflow_dispatch:
inputs:
tag:
description: "Release tag, e.g. v0.1.0-alpha.2 (must already point at this commit for Stage B)"
description: "Release tag, e.g. v0.1.0-alpha.3 (must already point at this commit for Stage B)"
required: true
publish:
description: "Run Stage B (publish to npm + GitHub prerelease)"
Expand Down
112 changes: 112 additions & 0 deletions docs/releases/v0.1.0-alpha.3.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# Sentinel v0.1.0-alpha.3

> ⚠️ **Alpha, pre-1.0.** Not production-ready; APIs may change without
> notice between prereleases.

A security release. A full audit of Sentinel found ways for a package
author, a lockfile, an HTTP client or a sandboxed install script to get past
the checks Sentinel promises. This release closes them, then closes four
follow-up detection gaps in install-script analysis. ADR-0056 records each
decision.

## Install

```bash
npm install -g @git-agentic/sentinel-cli@alpha @git-agentic/sentinel-proxy@alpha
```

## Upgrade notes (breaking, pre-1.0)

- The proxy and the steward listen on `127.0.0.1` by default. A deployment
reached over the network must set `SENTINEL_HOST` (proxy) or
`SENTINEL_STEWARD_HOST` (steward).
- `SENTINEL_POLICY` must be exactly `observe` or `block`; anything else stops
startup.
- In open mode, history import and retraction need `SENTINEL_PUBLISH_TOKENS`.
- `sentinel install --enforce` needs npm 7 or newer for dependency scripts,
and refuses packages npm records only with a sha1 hash.
- A lockfile entry from git, from a URL, or with no integrity hash now
blocks `audit-tree`. Older yarn v1 lockfiles from private registries can
hit this.
- Steward: challenges expire after 30 days and are single use. After the
upgrade, every challenge verified before it counts as used, so pending
approvals, transfers, renewals and rulings need a fresh challenge. Claims
linked only through a same-named GitHub or GitLab org now go through the
Tier-2 review.
- `ClaimSteward.approve` is async, and transfer signing takes the current
challenge id.
- Cached audits are re-run once after upgrading (`AUDIT_REVISION` 6).

## Fixed

**Scanner** (#84)

- Tarballs are read the way npm installs them: type-7 entries, npm path
normalization, both readings of a backslash, PAX paths and trailing
separators. A second or hidden root `package.json` raises a critical
`manifest-confusion` finding.
- JavaScript that starts with a magic-byte label is still scanned. Nested
compression counts against the unpack cap. One malformed field no longer
disables a rule, and the regexes on the request path are linear.

**Trust inputs** (#84)

- Trusted-publisher repository and ref come from the Fulcio certificate,
not the signer-written predicate. An unmatched signature key id counts as
unsigned. Every SRI token in a lockfile is verified.

**Proxy** (#84)

- The npm compatibility routes no longer forward client credentials
upstream, and their bodies are capped.

**Sandbox** (#84)

- The macOS profile is passed inline instead of through a temp file a
script could rewrite.
- On Linux, bubblewrap gets its own pid namespace and session, and masks
local IPC sockets (session bus, Docker and other container runtimes).
- `launchctl`, `open`, `systemd-run` and similar tools are carved out.
- Enforced installs bind each dependency script to its audited integrity.

**Steward** (#84)

- Tier 1 needs a homepage or repository host under the claimed domain.
- Disputes survive freezes, and transfer signatures bind the current proof.

**Action, CLI and CI** (#84)

- The Action escapes workflow commands and Markdown, and the CLI strips
terminal escapes.
- The release workflow installs third-party code only in a job with no token.

**Install-script analysis** (#89, #90, #91, #92)

- A hook that calls `npm`, `pnpm`, `yarn` or `bun` is followed into the
package's own scripts, including `pre`/`post` hooks and npm's aliases.
- Scripts run through `source`, pipes, `/usr/bin/env`, `tsx`/`ts-node` or
`node .` are scanned.
- Preloads and command names served by the package's own bundled
`node_modules` are scanned. Node built-ins are excluded.
- Very deep code no longer drops the native-payload loader check into a
name-matching fallback; the loader-chain analysis now walks the syntax tree
iteratively.

**Dependencies** (#84)

- Production advisories are fixed (body-parser, hono, fast-uri, qs, zod);
`npm audit --omit=dev` reports none.

## Known limits

Recorded in ADR-0056 and the threat model: abstract unix sockets stay
reachable on Linux when `network` is approved, a sandboxed process can
outlive its script on macOS, and a few narrow shell-parsing corner cases in
install-script analysis.

## Feedback

Bugs and detection gaps:
[github.com/git-agentic/pkg-registry/issues](https://github.com/git-agentic/pkg-registry/issues).
Exploitable flaws: [private vulnerability reporting](https://github.com/git-agentic/pkg-registry/security)
(see SECURITY.md).
34 changes: 17 additions & 17 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "sentinel-registry",
"version": "0.1.0-alpha.2",
"version": "0.1.0-alpha.3",
"private": true,
"description": "Sentinel — an agent-auditable security/audit proxy for the npm ecosystem (Phase 1 wedge).",
"license": "Apache-2.0",
Expand Down
6 changes: 3 additions & 3 deletions packages/action/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@git-agentic/sentinel-action",
"version": "0.1.0-alpha.2",
"version": "0.1.0-alpha.3",
"description": "Sentinel CI runner: self-booting dependency-tree audit for GitHub Actions (sentinel-ci) — audits a lockfile, writes a CycloneDX SBOM, and posts a PR verdict.",
"license": "Apache-2.0",
"type": "module",
Expand Down Expand Up @@ -42,8 +42,8 @@
"sbom"
],
"dependencies": {
"@git-agentic/sentinel-core": "0.1.0-alpha.2",
"@git-agentic/sentinel-proxy": "0.1.0-alpha.2"
"@git-agentic/sentinel-core": "0.1.0-alpha.3",
"@git-agentic/sentinel-proxy": "0.1.0-alpha.3"
},
"devDependencies": {
"@types/node": "^24.13.2"
Expand Down
6 changes: 3 additions & 3 deletions packages/cli/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@git-agentic/sentinel-cli",
"version": "0.1.0-alpha.2",
"version": "0.1.0-alpha.3",
"description": "Sentinel CLI: pre-install audit verdicts, whole-tree lockfile audits, registry-redirected npm/npx, policy tooling, and sandbox-enforced installs.",
"license": "Apache-2.0",
"type": "module",
Expand Down Expand Up @@ -44,8 +44,8 @@
"sandbox"
],
"dependencies": {
"@git-agentic/sentinel-core": "0.1.0-alpha.2",
"@git-agentic/sentinel-sandbox": "0.1.0-alpha.2",
"@git-agentic/sentinel-core": "0.1.0-alpha.3",
"@git-agentic/sentinel-sandbox": "0.1.0-alpha.3",
"commander": "^15.0.0"
},
"devDependencies": {
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ const program = new Command();
program
.name("sentinel")
.description("Agent-auditable security layer for npm — pre-install audit verdicts.")
.version("0.1.0-alpha.2");
.version("0.1.0-alpha.3");

program
.command("audit")
Expand Down
2 changes: 1 addition & 1 deletion packages/core/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@git-agentic/sentinel-core",
"version": "0.1.0-alpha.2",
"version": "0.1.0-alpha.3",
"description": "Sentinel audit engine: deterministic heuristic rules, scoring, data model, lockfile parsing, SBOM export, and pluggable LLM adapter.",
"license": "Apache-2.0",
"type": "module",
Expand Down
2 changes: 1 addition & 1 deletion packages/core/src/audit.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ import type {
import type { Advisory } from "./advisory-corpus.js";
import type { VulnAdvisory } from "./vuln-corpus.js";

export const ENGINE_VERSION = "0.1.0-alpha.2";
export const ENGINE_VERSION = "0.1.0-alpha.3";
/** Bump whenever rule or extraction semantics change: cached and stored audits from another revision are recomputed. */
export const AUDIT_REVISION = 6;

Expand Down
4 changes: 2 additions & 2 deletions packages/mcp/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@git-agentic/sentinel-mcp",
"version": "0.1.0-alpha.2",
"version": "0.1.0-alpha.3",
"description": "Sentinel MCP server: agent-native pre-install audit tools backed by the Sentinel proxy (stdio Model Context Protocol server).",
"license": "Apache-2.0",
"type": "module",
Expand Down Expand Up @@ -42,7 +42,7 @@
"npm-audit"
],
"dependencies": {
"@git-agentic/sentinel-core": "0.1.0-alpha.2",
"@git-agentic/sentinel-core": "0.1.0-alpha.3",
"@modelcontextprotocol/sdk": "^1.29.0",
"zod": "^4.6.7"
},
Expand Down
2 changes: 1 addition & 1 deletion packages/mcp/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import { TOOLS } from "./tools.js";

/** Build an McpServer with every Sentinel tool registered against `client`. */
export function createMcpServer(client: ProxyClient): McpServer {
const server = new McpServer({ name: "sentinel", version: "0.1.0-alpha.2" });
const server = new McpServer({ name: "sentinel", version: "0.1.0-alpha.3" });
for (const tool of TOOLS) {
server.registerTool(
tool.name,
Expand Down
4 changes: 2 additions & 2 deletions packages/proxy/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@git-agentic/sentinel-proxy",
"version": "0.1.0-alpha.2",
"version": "0.1.0-alpha.3",
"description": "Sentinel registry proxy: transparently serves npm packages while intercepting and auditing each tarball, with an authoritative native publish path, verified claims, and time-locked retraction.",
"license": "Apache-2.0",
"type": "module",
Expand Down Expand Up @@ -44,7 +44,7 @@
"package-retraction"
],
"dependencies": {
"@git-agentic/sentinel-core": "0.1.0-alpha.2",
"@git-agentic/sentinel-core": "0.1.0-alpha.3",
"commander": "^15.0.0",
"express": "^5.2.1",
"express-rate-limit": "^8.5.2"
Expand Down
4 changes: 2 additions & 2 deletions packages/sandbox/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@git-agentic/sentinel-sandbox",
"version": "0.1.0-alpha.2",
"version": "0.1.0-alpha.3",
"description": "Sentinel capability sandbox: generate an OS sandbox profile from approved capabilities and run lifecycle scripts under it (macOS Seatbelt / Linux bubblewrap, deny-by-default).",
"license": "Apache-2.0",
"type": "module",
Expand Down Expand Up @@ -43,7 +43,7 @@
"least-privilege"
],
"dependencies": {
"@git-agentic/sentinel-core": "0.1.0-alpha.2"
"@git-agentic/sentinel-core": "0.1.0-alpha.3"
},
"devDependencies": {
"@types/node": "^24.13.2"
Expand Down
4 changes: 2 additions & 2 deletions packages/steward/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@git-agentic/sentinel-steward",
"version": "0.1.0-alpha.2",
"version": "0.1.0-alpha.3",
"description": "Sentinel namespace-claim steward: DNS TXT claim verification, renewal/freeze lifecycle, timelocked transfers, and Ed25519-signed claim/retraction corpus releases.",
"license": "Apache-2.0",
"type": "module",
Expand Down Expand Up @@ -42,7 +42,7 @@
"npm-registry"
],
"dependencies": {
"@git-agentic/sentinel-core": "0.1.0-alpha.2",
"@git-agentic/sentinel-core": "0.1.0-alpha.3",
"express": "^5.2.1",
"express-rate-limit": "^8.5.2"
},
Expand Down
Loading