JavaScript SDK and DSN
Mask keys in your logs before they are written, flag responses that carry a secret, and report your runtime and the hosts your app calls.
These pages describe ShellOrbit as it runs today. Breaking changes to the HTTP API are announced before they ship, and existing request and response shapes stay supported.
The SDK masks keys in your Node.js logs, reports where they leaked, tells Incident Alerts which runtime you are on, and on Pro and Business watches for new outbound hosts.
Install
Version 1.2.0, Node 20 or later.
npm install @shellorbit/sdkimport ShellOrbit from "@shellorbit/sdk";
ShellOrbit.init({ dsn: process.env.SHELLORBIT_DSN });Call init once, early. Get the DSN from Leak Alarm, SDK: it looks like https://pk_…@api.shellorbit.com/prj_…. A DSN can only report findings for its own project, so it is safe in server configuration; keep it out of browser code. Rotate the key and the old DSN is refused at once. An account holds 20 projects.
Options
| Option | Default | What it does |
|---|---|---|
dsn | none | Where findings go. Without it the SDK does nothing |
console | true | Mask secrets in console output |
fingerprints | true | Send fingerprints of the keys in process.env at start up |
tripwire | false | Plant a fake AWS key in process.env |
runtimeReport | true | Send the Node.js and OpenSSL versions at start up and once a day |
outboundWatch | true | Report the hostnames your app and its packages connect to, for outbound traffic watch |
debug | false | Print the SDK’s own problems with console.error |
init returns a handle with flush() and close().
Features
| Feature | How |
|---|---|
| Mask keys in logs | Automatic for console; use pinoOptions() or winstonFormat() for pino or winston. A key becomes sk_…a1b2 before the line is written, and where it was logged is reported |
| Guard responses | expressGuard() or withGuard() reports a server only key, such as a Supabase service role key, in a response as critical. { block: true } blocks the response instead |
| Fingerprint your keys | Salted one way fingerprints of your real keys. On Starter and up, a match in a log drain is reported as your real key |
| Runtime report | Node.js and OpenSSL versions, platform, and architecture, at start up and daily |
| Outbound hosts | Hostname, port, protocol, and the npm package or app that opened each connection; never a path, header, or body. Findings on Pro and Business |
| Tripwire | tripwire: true plants a fake AWS key as BACKUP_AWS_ACCESS_KEY_ID. Uses one of your tripwires; Starter and up |
import pino from "pino";
import { pinoOptions } from "@shellorbit/sdk";
const log = pino({ ...pinoOptions() });import { expressGuard } from "@shellorbit/sdk";
app.use(expressGuard()); // report only
app.use(expressGuard({ block: true })); // or replace the response with a 500
Privacy
The SDK never sends a key in full, a request path, a header or body, or environment variables. With outbound traffic watch on, which is the default, it sends the hostnames your app connects to and the name of the npm package that opened each connection; turn that off with outboundWatch: false. It never throws and never slows a request; if ShellOrbit is unreachable it retries later. ShellOrbit refuses any finding whose value is not masked.
Turn off the runtime report with ShellOrbit.init({ dsn: process.env.SHELLORBIT_DSN, runtimeReport: false }). You can still declare your runtime in the dashboard.
Limits
| Limit | Value |
|---|---|
| Requests | 10 a second, 60 a minute per project |
| Findings | 50 per request, 10,000 a day per project |
| Runtime reports | 24 a day per project, never counted as events |
Past a limit the API answers 429 with Retry-After and the SDK waits. Findings and reports are activity, never billed.