@watchtowerobservability/node 0.2.0 → 0.4.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.
Files changed (94) hide show
  1. package/README.md +186 -3
  2. package/dist/cjs/appsec.d.ts +95 -0
  3. package/dist/cjs/appsec.js +206 -0
  4. package/dist/cjs/iast.d.ts +27 -0
  5. package/dist/cjs/iast.js +138 -0
  6. package/dist/cjs/index.d.ts +3 -0
  7. package/dist/cjs/index.js +14 -1
  8. package/dist/cjs/integrations/amqp.d.ts +13 -0
  9. package/dist/cjs/integrations/amqp.js +96 -0
  10. package/dist/cjs/integrations/bullmq.d.ts +19 -0
  11. package/dist/cjs/integrations/bullmq.js +83 -0
  12. package/dist/cjs/integrations/cache.d.ts +13 -0
  13. package/dist/cjs/integrations/cache.js +51 -0
  14. package/dist/cjs/integrations/db.d.ts +62 -0
  15. package/dist/cjs/integrations/db.js +288 -0
  16. package/dist/cjs/integrations/duckdb.d.ts +22 -0
  17. package/dist/cjs/integrations/duckdb.js +66 -0
  18. package/dist/cjs/integrations/graphile-worker.d.ts +22 -0
  19. package/dist/cjs/integrations/graphile-worker.js +50 -0
  20. package/dist/cjs/integrations/level.d.ts +18 -0
  21. package/dist/cjs/integrations/level.js +71 -0
  22. package/dist/cjs/integrations/lmdb.d.ts +26 -0
  23. package/dist/cjs/integrations/lmdb.js +78 -0
  24. package/dist/cjs/integrations/messaging.d.ts +17 -0
  25. package/dist/cjs/integrations/messaging.js +73 -0
  26. package/dist/cjs/integrations/mqtt.d.ts +7 -0
  27. package/dist/cjs/integrations/mqtt.js +41 -0
  28. package/dist/cjs/integrations/nats.d.ts +17 -0
  29. package/dist/cjs/integrations/nats.js +73 -0
  30. package/dist/cjs/integrations/orm.d.ts +47 -0
  31. package/dist/cjs/integrations/orm.js +93 -0
  32. package/dist/cjs/integrations/pg-boss.d.ts +8 -0
  33. package/dist/cjs/integrations/pg-boss.js +63 -0
  34. package/dist/cjs/integrations/pools.d.ts +41 -0
  35. package/dist/cjs/integrations/pools.js +94 -0
  36. package/dist/cjs/integrations/postgres.d.ts +12 -0
  37. package/dist/cjs/integrations/postgres.js +92 -0
  38. package/dist/cjs/integrations/sqlite.d.ts +36 -0
  39. package/dist/cjs/integrations/sqlite.js +125 -0
  40. package/dist/cjs/pprof.d.ts +6 -0
  41. package/dist/cjs/pprof.js +88 -0
  42. package/dist/cjs/profiling.d.ts +4 -1
  43. package/dist/cjs/profiling.js +18 -8
  44. package/dist/cjs/sql.d.ts +19 -0
  45. package/dist/cjs/sql.js +332 -0
  46. package/dist/cjs/test-plan.d.ts +10 -1
  47. package/dist/cjs/test-plan.js +91 -1
  48. package/dist/esm/appsec.d.ts +95 -0
  49. package/dist/esm/appsec.js +193 -0
  50. package/dist/esm/iast.d.ts +27 -0
  51. package/dist/esm/iast.js +130 -0
  52. package/dist/esm/index.d.ts +3 -0
  53. package/dist/esm/index.js +14 -1
  54. package/dist/esm/integrations/amqp.d.ts +13 -0
  55. package/dist/esm/integrations/amqp.js +92 -0
  56. package/dist/esm/integrations/bullmq.d.ts +19 -0
  57. package/dist/esm/integrations/bullmq.js +79 -0
  58. package/dist/esm/integrations/cache.d.ts +13 -0
  59. package/dist/esm/integrations/cache.js +46 -0
  60. package/dist/esm/integrations/db.d.ts +62 -0
  61. package/dist/esm/integrations/db.js +239 -0
  62. package/dist/esm/integrations/duckdb.d.ts +22 -0
  63. package/dist/esm/integrations/duckdb.js +29 -0
  64. package/dist/esm/integrations/graphile-worker.d.ts +22 -0
  65. package/dist/esm/integrations/graphile-worker.js +46 -0
  66. package/dist/esm/integrations/level.d.ts +18 -0
  67. package/dist/esm/integrations/level.js +35 -0
  68. package/dist/esm/integrations/lmdb.d.ts +26 -0
  69. package/dist/esm/integrations/lmdb.js +42 -0
  70. package/dist/esm/integrations/messaging.d.ts +17 -0
  71. package/dist/esm/integrations/messaging.js +64 -0
  72. package/dist/esm/integrations/mqtt.d.ts +7 -0
  73. package/dist/esm/integrations/mqtt.js +38 -0
  74. package/dist/esm/integrations/nats.d.ts +17 -0
  75. package/dist/esm/integrations/nats.js +70 -0
  76. package/dist/esm/integrations/orm.d.ts +47 -0
  77. package/dist/esm/integrations/orm.js +86 -0
  78. package/dist/esm/integrations/pg-boss.d.ts +8 -0
  79. package/dist/esm/integrations/pg-boss.js +60 -0
  80. package/dist/esm/integrations/pools.d.ts +41 -0
  81. package/dist/esm/integrations/pools.js +89 -0
  82. package/dist/esm/integrations/postgres.d.ts +12 -0
  83. package/dist/esm/integrations/postgres.js +55 -0
  84. package/dist/esm/integrations/sqlite.d.ts +36 -0
  85. package/dist/esm/integrations/sqlite.js +84 -0
  86. package/dist/esm/pprof.d.ts +6 -0
  87. package/dist/esm/pprof.js +85 -0
  88. package/dist/esm/profiling.d.ts +4 -1
  89. package/dist/esm/profiling.js +17 -8
  90. package/dist/esm/sql.d.ts +19 -0
  91. package/dist/esm/sql.js +324 -0
  92. package/dist/esm/test-plan.d.ts +10 -1
  93. package/dist/esm/test-plan.js +89 -1
  94. package/package.json +171 -1
package/README.md CHANGED
@@ -47,6 +47,32 @@ Each lives at its own subpath, so nothing is loaded that you do not import.
47
47
  | NestJS | `.../nestjs` | `app.useGlobalInterceptors(new WatchtowerInterceptor())` (add express or fastify integration for spans) |
48
48
  | Next.js server | `.../next` | `instrumentation.js`: `module.exports = require('@watchtowerobservability/node/next')` (exports `register`, `onRequestError`) |
49
49
  | Prisma | `.../prisma` | `prisma.$extends(watchtowerExtension())` |
50
+ | BullMQ | `.../bullmq` | `import * as bullmq from 'bullmq'; instrumentBullMQ(bullmq)` before creating queues and workers |
51
+ | postgres.js (>= 4) | `.../postgres` | `instrumentPostgres()` once at startup |
52
+ | SQLite (`node:sqlite`) | `.../sqlite` | `import * as sqlite from 'node:sqlite'; instrumentNodeSqlite(sqlite)` |
53
+ | better-sqlite3 | `.../sqlite` | `instrumentBetterSqlite3(Database)` (the default export) |
54
+ | sqlite3 | `.../sqlite` | `instrumentSqlite3(sqlite3)` |
55
+ | libSQL / Turso | `.../sqlite` | `const db = instrumentLibsql(createClient({ url }))` |
56
+ | DuckDB | `.../duckdb` | `import * as duckdb from '@duckdb/node-api'; instrumentDuckDB(duckdb)` (classic `duckdb` too) |
57
+ | LMDB (lmdb-js) | `.../lmdb` | `instrumentLmdb(open({ path }))` after `init` |
58
+ | LevelDB / RocksDB | `.../level` | `instrumentLevel(new ClassicLevel(dir))`, `instrumentLevel(rocksdb(dir), { system: 'rocksdb' })` |
59
+ | node-cache, lru-cache, Keyv | `.../cache` | `instrumentNodeCache(cache, 'sessions')`, `instrumentLruCache(lru)`, `instrumentKeyv(keyv)` after `init` |
60
+ | MongoDB pool | `.../pools` | `instrumentMongoPool(client)` after `init` (pool gauges, wait/use time, timeouts from CMAP events) |
61
+ | mysql2 pool | `.../pools` | `instrumentMysql2Pool(pool)` (callback or `.promise()` pool) |
62
+ | Any pool (e.g. node-postgres) | `.../pools` | `observePool('postgresql', 'main', () => ({ used: p.totalCount - p.idleCount, idle: p.idleCount, pending: p.waitingCount, max: 10 }))` |
63
+ | Drizzle | `.../orm` | `instrumentDrizzle(db, 'postgresql')` once per `drizzle(...)` instance |
64
+ | Kysely | `.../orm` | `new Kysely({ dialect, log: kyselyLog('postgresql') })` |
65
+ | TypeORM | `.../orm` | `instrumentTypeORM(dataSource)` |
66
+ | Sequelize | `.../orm` | `new Sequelize(url, { benchmark: true, logging: sequelizeLogging('postgresql') })` |
67
+ | MikroORM | `.../orm` | `MikroORM.init({ loggerFactory: mikroOrmLoggerFactory(DefaultLogger, 'postgresql') })` |
68
+ | amqplib (RabbitMQ) | `.../amqp` | `instrumentAmqplib(await conn.createChannel())` once (patches the channel class) |
69
+ | rabbitmq-client | `.../amqp` | `instrumentRabbitmqClient(rabbit)` before `createPublisher`/`createConsumer` |
70
+ | NATS (nats.js) | `.../nats` | `import * as nats from 'nats'; instrumentNats(nc, nats)` |
71
+ | MQTT (mqtt.js) | `.../mqtt` | `instrumentMqtt(client)` (context propagates on MQTT 5 clients) |
72
+ | pg-boss | `.../pg-boss` | `instrumentPgBoss(boss)` before `send`/`work` |
73
+ | Graphile Worker | `.../graphile-worker` | `run({ taskList: wrapTaskList(tasks) })`; `instrumentAddJob(utils)` |
74
+ | kafkajs | upstream | use `@opentelemetry/instrumentation-kafkajs` |
75
+ | SQL normalizer | `.../sql` | `normalizeAndHash(sql)` -> `[literal-free text, db.query.hash]` |
50
76
  | AWS Lambda | `.../lambda` | `exports.handler = wrapHandler(async (event, ctx) => ...)` (async handlers; flushes before freeze) |
51
77
  | Azure Functions | `.../azure-functions` | `app.http('fn', { handler: wrapFunction(async (req, ctx) => ...) })` (cold start, trigger, invocation id; flushes) |
52
78
  | pino | `.../logs` | `pino(opts, pinoStream())` |
@@ -61,22 +87,179 @@ Each lives at its own subpath, so nothing is loaded that you do not import.
61
87
  GenAI spans follow the OTel GenAI semantic conventions (model, token usage, finish reasons); prompt and
62
88
  completion text is not recorded. Streaming calls end their span at creation, without token usage.
63
89
 
90
+ ### BullMQ
91
+
92
+ `instrumentBullMQ(bullmq)` patches the module you pass, so it works the same under ESM and CommonJS.
93
+ `Queue.add` and `addBulk` get PRODUCER spans (`send <queue>`); each job a `Worker` runs gets a
94
+ CONSUMER span (`process <queue>`) whose parent is the producer span, so one trace runs from the
95
+ request that queued the job to the job itself. The context travels in the job data under `_wt`
96
+ (object data only) and is removed before your processor sees `job.data`. Attributes follow the OTel
97
+ messaging conventions: `messaging.system=bullmq`, `messaging.destination.name`,
98
+ `messaging.operation.type` (`send`/`process`), `messaging.operation.name`, `messaging.message.id`,
99
+ `messaging.batch.message_count`, `messaging.bullmq.job.attempt` and `messaging.bullmq.job.delay_ms`.
100
+ Sandboxed processors (a file path instead of a function) run in a child process and get no consumer
101
+ span.
102
+
103
+ ### postgres.js
104
+
105
+ postgres.js has no OTel instrumentation; from 4.0 it publishes every query on the `postgres:query`
106
+ diagnostics tracing channel. `instrumentPostgres()` subscribes to it and records a CLIENT span per
107
+ query, child of the active span: `db.system=postgresql`, `db.operation.name`, `db.namespace`,
108
+ `server.address`/`server.port`, `db.query.summary` (operation and first table, e.g.
109
+ `SELECT users`) and `db.query.hash` (see below; the statement text and parameters are never recorded).
110
+ A failed query sets the span
111
+ to error with its SQLSTATE in `db.response.status_code` (the error message is not recorded: it can
112
+ quote values). It returns an unsubscribe function.
113
+
114
+ ### Datastore spans: summary, hash, N+1
115
+
116
+ Every datastore integration below (and postgres.js) records a CLIENT span per call, child of the
117
+ active span, following the OTel database conventions: `db.system.name`, `db.operation.name`,
118
+ `db.collection.name`, `db.namespace` and, for SQL, `db.query.summary` (also the span name, e.g.
119
+ `SELECT users`) and `db.query.hash`. The hash comes from the shared SQL normalizer (literals become
120
+ `?`, comments go, `IN (1, 2, 3)` becomes `IN (?+)`), so it is the same hash Watchtower computes on the
121
+ server and spans join the Datastores views. The algorithm is specified in
122
+ `docs/product/instrumentation/sql-normalization.md` and exported at `.../sql`.
123
+
124
+ Statement text and parameters are never recorded by default. Pass `{ queryText: true }` (or set
125
+ `WATCHTOWER_DB_QUERY_TEXT=1`) to add `db.query.text`, which is then the literal-free text. A
126
+ statement that runs more than 5 times under one parent span gets `db.n_plus_one=true` and
127
+ `db.query.repeat_count` from the sixth run on; change the limit with `{ nPlusOne: n }` or
128
+ `WATCHTOWER_DB_N_PLUS_ONE` (0 turns it off). Failed calls set the span to error with the driver's
129
+ code in `db.response.status_code` and `error.type`; the error message is not recorded (it can quote
130
+ values). All integrations take the module, class or instance you pass, so they work under ESM and
131
+ CommonJS. Metric helpers use the global meter: call them after `init`.
132
+
133
+ ### Embedded stores and caches
134
+
135
+ - **SQLite.** `instrumentNodeSqlite`, `instrumentBetterSqlite3` and `instrumentSqlite3` trace `exec`
136
+ and prepared `run`/`get`/`all` (sqlite3: `run`/`get`/`all`/`exec`/`each` on `Database`; the span
137
+ ends in your callback, which keeps the caller's context). `instrumentLibsql(client)` traces
138
+ `execute`, `executeMultiple`, `batch` and the same calls on transactions. `observeSqliteFile(path)`
139
+ reports `wt.embedded.file.size` and `wt.embedded.wal.size`. Not traced: `iterate()`, sqlite3
140
+ `Statement` objects.
141
+ - **DuckDB.** `instrumentDuckDB(duckdb)` traces `DuckDBConnection.run*`/`stream*` (Neo API) or the
142
+ classic `Database`/`Connection` callbacks; `observeDuckDBFile(path)` reports file and WAL size.
143
+ Prepared statements are not traced.
144
+ - **LMDB.** `instrumentLmdb(db)` traces async writes (`put`, `remove`, `ifVersion`, `ifNoExists`,
145
+ `clearAsync`, `drop`), `getMany` and `transaction` (calls inside it are child spans), on the root
146
+ and on `openDB` sub-databases. Synchronous `get` is memory-mapped and gets no span. It reports
147
+ `wt.embedded.map.size`, `.map.used`, `.entries`, `.readers` and `.file.size`.
148
+ - **LevelDB / RocksDB.** `instrumentLevel(db, { system })` traces `get`, `getMany`, `put`, `del`,
149
+ `batch` and `clear` (promise or callback form) on the db and its sublevels, and reports the store
150
+ directory size as `wt.embedded.file.size`. Iterators and the chained `batch()` builder are not
151
+ traced.
152
+ - **Caches.** `instrumentNodeCache`, `instrumentLruCache` and `instrumentKeyv` count
153
+ `wt.embedded.cache.hits` and `.misses` (a `get` returning `undefined` is a miss; multi-key gets count
154
+ per key) and, where the cache knows it, `wt.embedded.cache.entries`. Caches get metrics, not
155
+ spans.
156
+
157
+ ### Connection pools
158
+
159
+ Pool metrics follow the OTel database conventions and carry `db.system.name` and
160
+ `db.client.connection.pool.name`: `db.client.connection.count{db.client.connection.state=used|idle}`,
161
+ `db.client.connection.max`, `db.client.connection.pending_requests`, the histograms
162
+ `db.client.connection.wait_time` and `db.client.connection.use_time` (seconds) and the counter
163
+ `db.client.connection.timeouts`. Call these after `init`; the gauges are read at each export.
164
+ `instrumentMongoPool(client)` builds them per server address from the driver's connection-pool
165
+ events (wait time needs driver 6.9 or newer). `instrumentMysql2Pool(pool)` reads the pool's own
166
+ counts and measures use time from acquire to release. It is named `host:port/database` unless you
167
+ pass a name. mysql2 reports no queue wait and has no acquire timeout, so those two stay empty.
168
+ For any other pool, `observePool(system, name, read)` takes your own `read()` function. It returns
169
+ `wait(s)`, `use(s)`, `timeout()` and `stop()`.
170
+
171
+ ### ORMs
172
+
173
+ Each ORM query becomes a CLIENT span with the summary, hash and N+1 hint described above.
174
+ - **Drizzle and TypeORM:** the query runs inside the span. Drizzle transactions run on their own
175
+ session and get no spans.
176
+ - **Kysely, Sequelize and MikroORM:** the span is built from the query time the ORM reports and
177
+ ends when the query does. Sequelize needs `benchmark: true` and does not report failed queries
178
+ with a timing.
179
+ - **TypeORM:** maps `options.type` to the OTel names (postgres to postgresql, mssql to
180
+ microsoft.sql_server, the sqlite drivers to sqlite).
181
+
182
+ If you also instrument the driver underneath, each query gets one ORM span and one driver span.
183
+
184
+ ### Queues and brokers
185
+
186
+ Every broker and job-queue integration records a PRODUCER span when a message or job is sent and a
187
+ CONSUMER span when it is processed. The consumer span is a child of the producer span and also links
188
+ to it, so one trace runs from the request to the handler and Watchtower can compute queue lag
189
+ (`wt.messaging.lag_ms`). Attributes follow the OTel messaging conventions: `messaging.system`,
190
+ `messaging.destination.name`, `messaging.operation.type` (`send`/`process`), `messaging.operation.name`,
191
+ `messaging.message.id`, `messaging.message.body.size`, `messaging.batch.message_count` and
192
+ `messaging.consumer.group.name` where the library has one. A failed handler marks its span as an error
193
+ with `error.type`; the error message is not recorded.
194
+
195
+ - **amqplib**: `publish` and `sendToQueue` put `traceparent`/`tracestate` into `options.headers`
196
+ (your headers are kept); `consume` callbacks run in the consumer span. Also recorded:
197
+ `messaging.rabbitmq.destination.routing_key`, `messaging.rabbitmq.message.delivery_tag` and
198
+ `.redelivered`. A ConfirmChannel is a separate class, so instrument one of those too if you use it.
199
+ - **rabbitmq-client**: `publisher.send(envelope | queue, body)` adds the context to the envelope
200
+ headers; `createConsumer` handlers run in the consumer span.
201
+ - **nats**: `publish` and `request` add the context as NATS headers. A `callback` subscription runs
202
+ each callback in the consumer span. With `for await (const m of sub)`, each message's span runs from
203
+ receipt until the next iteration and is not active inside the loop body: spans you start there are
204
+ not its children, but the producer link still gives lag.
205
+ - **mqtt**: `publish`/`publishAsync` carry the context in MQTT 5 user properties, so only
206
+ `protocolVersion: 5` clients propagate it; older clients get spans that are not linked. `message`
207
+ listeners run in the consumer span. `publish` spans end when the call returns; use `publishAsync`
208
+ to include the QoS 1/2 ack time.
209
+ - **pg-boss**: `send` and `insert` (v9 and v10 forms) carry the context in job data under `_wt`
210
+ (object data only). It is removed before your `work` handler runs. A batch gets one consumer span
211
+ linked to every job's producer. `messaging.system` is `pg-boss`, since OTel defines no value for it.
212
+ `sendAfter`, `sendThrottled`, `sendDebounced` and `sendSingleton` bypass `send`, so their jobs carry
213
+ no context.
214
+ - **Graphile Worker**: `instrumentAddJob(utils)` (or the runner from `run`) adds `_wt` to the payload.
215
+ `wrapTaskList` runs each task in a consumer span, strips `_wt`, and instruments `helpers.addJob` so
216
+ follow-up jobs stay in the trace. `quickAddJob` cannot be patched under ESM; use `utils.addJob`.
217
+ - **kafkajs**: upstream `@opentelemetry/instrumentation-kafkajs` already covers it.
218
+
64
219
  ## Profiling
65
220
 
221
+ Set `WT_PROFILING=1` and `init()` starts the profiler with the same key, endpoint, service and
222
+ release as traces. Or start it yourself:
223
+
66
224
  ```ts
67
225
  import { startProfiling } from '@watchtowerobservability/node/profiling';
68
226
  await startProfiling({ service: 'api' }); // key and endpoint from WT_INGEST_KEY / WT_OTLP_ENDPOINT
69
227
  ```
70
228
 
71
- V8's own CPU sampler (`node:inspector`, 100 Hz, no native addon) is folded and posted to the
72
- gateway's `/ingest` every 15 s as `<service>.cpu`. Idle time is left out. `withSpan(() => work())`
229
+ V8's own CPU sampler (`node:inspector`, 100 Hz, no native addon) is encoded as pprof (no extra
230
+ dependency) and posted to the gateway's `/v1/profiles?format=pprof&service=<service>&version=<release>`
231
+ every 60 s. Idle time is left out. Samples taken inside `withSpan` carry `span_id` and `trace_id`
232
+ labels. `shutdown()` uploads the last partial period. `withSpan(() => work())`
73
233
  labels samples with the active OpenTelemetry span, so a trace links to its exact profile. By default
74
234
  only its synchronous part counts. `startProfiling({ asyncSpans: true })` (or
75
235
  `enableAsyncSpanLabels()`) also labels code after each `await`, through AsyncLocalStorage and V8
76
- promise hooks. It is opt-in because its overhead has not been measured. Plain callbacks it starts
236
+ promise hooks. It is opt-in because its overhead is not part of the benchmark below. Plain callbacks it starts
77
237
  (timers, events) are labeled only from their own `await`s on. Past 100 000 labeled intervals in one
78
238
  upload period, the rest of that period is unlabeled.
79
239
 
240
+ ### Measuring profiler overhead
241
+
242
+ The profiler's CPU cost depends on your machine and workload, so measure it instead of trusting a
243
+ number: `WT_BENCH=1 npx vitest run test/overhead.bench.test.ts` (in `sdks/node`) runs a CPU-bound loop
244
+ with and without the 100 Hz sampler, prints the median overhead in percent and fails above
245
+ `WT_BENCH_MAX_PCT` (default 2). `WT_BENCH_ROUNDS` and `WT_BENCH_WORK_MS` tune the run. We publish no
246
+ measured figure here; run it on your hardware. The benchmark excludes the once-a-minute upload.
247
+
248
+ ## App and API Protection
249
+
250
+ An in-app WAF fed by your project's ruleset (key scope `probes:read`). In `monitor` mode it
251
+ records attacks on the server span. In `block` mode, and always for denylisted IPs and users, it
252
+ answers 403 before your handler runs.
253
+
254
+ ```ts
255
+ import { startAppsec, appsecMiddleware, trackLogin } from '@watchtowerobservability/node/appsec';
256
+ startAppsec(); // WT_API_URL, WT_INGEST_KEY, WT_SERVICE
257
+ app.use(appsecMiddleware());
258
+ // in the login handler: trackLogin(email, ok);
259
+ ```
260
+
261
+ See `docs/product/security/app-api-protection.md`.
262
+
80
263
  ## Configuration
81
264
 
82
265
  | Option | Env var | Default |
@@ -0,0 +1,95 @@
1
+ export type Field = 'path' | 'query' | 'user_agent' | 'body' | 'headers';
2
+ export interface AppsecRule {
3
+ id: string;
4
+ name?: string;
5
+ category: string;
6
+ severity?: string;
7
+ fields: Field[];
8
+ pattern: string;
9
+ }
10
+ export interface DenyEntry {
11
+ value: string;
12
+ /** Unix seconds; null: no expiry. */
13
+ expires_at?: number | null;
14
+ }
15
+ export interface Ruleset {
16
+ mode: 'monitor' | 'block';
17
+ rules: AppsecRule[];
18
+ denylist?: {
19
+ ip?: DenyEntry[];
20
+ user?: DenyEntry[];
21
+ };
22
+ poll_s?: number;
23
+ }
24
+ /** One request as the inspector sees it (decoded). */
25
+ export interface Inspected {
26
+ path: string;
27
+ query?: string;
28
+ user_agent?: string;
29
+ body?: string;
30
+ headers?: string;
31
+ ip?: string;
32
+ user?: string;
33
+ }
34
+ export interface Decision {
35
+ /** `allow`: nothing matched; `monitor`: matched, let through; `block`: answer 403. */
36
+ action: 'allow' | 'monitor' | 'block';
37
+ rule_id?: string;
38
+ category?: string;
39
+ match?: string;
40
+ }
41
+ /** Rule id recorded for denylist blocks (the worker reports them as their own signal). */
42
+ export declare const DENYLIST = "denylist";
43
+ /** Replace the active ruleset (what the poller calls; tests may call it directly). */
44
+ export declare function setRuleset(r: Ruleset | null): void;
45
+ /** Whether `id` is on the user denylist (call after authentication to refuse a listed user). */
46
+ export declare const isUserBlocked: (id: string, now?: number) => boolean;
47
+ /** Judge one request. Denylisted callers are blocked in either mode. */
48
+ export declare function inspect(req: Inspected, now?: number): Decision;
49
+ type Headers = Record<string, string | string[] | undefined>;
50
+ /** The slice of a Node request the inspector reads. */
51
+ export interface NodeRequest {
52
+ url?: string;
53
+ originalUrl?: string;
54
+ headers?: Headers;
55
+ socket?: {
56
+ remoteAddress?: string;
57
+ };
58
+ body?: unknown;
59
+ }
60
+ /** The slice of a Node response used to answer 403. */
61
+ export interface NodeResponse {
62
+ statusCode: number;
63
+ setHeader?(name: string, value: string): unknown;
64
+ end(body?: string): unknown;
65
+ }
66
+ /** Client IP: first `X-Forwarded-For` hop, else `X-Real-IP`, else the socket peer.
67
+ * shortcut: trusts the forwarding headers; run behind a proxy that overwrites them. */
68
+ export declare function clientIp(req: NodeRequest): string | undefined;
69
+ /** Decode a Node request into the inspector's fields. */
70
+ export declare function fromNode(req: NodeRequest, user?: string): Inspected;
71
+ /** Record a decision on the active span. */
72
+ export declare function annotate(d: Decision, ip?: string): void;
73
+ /** Inspect and, when blocked, answer 403. Returns true when the request was answered. */
74
+ export declare function handleRequest(req: NodeRequest, res: NodeResponse, user?: string): boolean;
75
+ /** Connect-style middleware; `user(req)` names the caller when the app already knows it. */
76
+ export declare function appsecMiddleware(o?: {
77
+ user?: (req: NodeRequest) => string | undefined;
78
+ }): (req: NodeRequest, res: NodeResponse, next: (err?: unknown) => void) => void;
79
+ /** Mark the current request as a login attempt; failed ones feed the account-takeover rules. */
80
+ export declare function trackLogin(login: string, success: boolean): void;
81
+ export interface AppsecOptions {
82
+ /** API base; default `WT_API_URL` or https://api.watchtower.dev */
83
+ apiUrl?: string;
84
+ /** Ingestion key with scope `probes:read`; default `WT_INGEST_KEY`. */
85
+ key?: string;
86
+ /** Default `WT_SERVICE` or `OTEL_SERVICE_NAME`. */
87
+ service?: string;
88
+ fetch?: typeof fetch;
89
+ }
90
+ /** Fetch the ruleset now and keep polling; `stop()` ends the polling. */
91
+ export declare function startAppsec(o?: AppsecOptions): {
92
+ ready: Promise<void>;
93
+ stop(): void;
94
+ };
95
+ export {};
@@ -0,0 +1,206 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.isUserBlocked = exports.DENYLIST = void 0;
4
+ exports.setRuleset = setRuleset;
5
+ exports.inspect = inspect;
6
+ exports.clientIp = clientIp;
7
+ exports.fromNode = fromNode;
8
+ exports.annotate = annotate;
9
+ exports.handleRequest = handleRequest;
10
+ exports.appsecMiddleware = appsecMiddleware;
11
+ exports.trackLogin = trackLogin;
12
+ exports.startAppsec = startAppsec;
13
+ // App and API Protection in-app WAF (W52). `startAppsec()` polls the project's ruleset from the
14
+ // edge (`GET /v1/appsec/ruleset`, an ingestion key with scope `probes:read`, ETag, every `poll_s`):
15
+ // mode, enabled pattern rules and the denylist. `appsecMiddleware()` (Express, Connect, any
16
+ // `(req, res, next)` stack) or `handleRequest(req, res)` (plain `http`, Fastify `onRequest`, Koa)
17
+ // inspects each request before the handler: path, query, User-Agent, other header values and an
18
+ // already parsed body, percent-decoded once, against the same rules the worker runs over stored
19
+ // spans. A match is recorded on the active server span (`appsec.event`, `appsec.rule_id`,
20
+ // `appsec.category`, `appsec.blocked`); in `block` mode, and for denylisted IPs or users in any
21
+ // mode, the request is answered with 403 problem+json and the handler never runs.
22
+ // Nothing is fetched or inspected until `startAppsec` is called; with no ruleset yet every
23
+ // request passes. Rules are matched case-insensitively; a rule that does not compile is skipped.
24
+ const api_1 = require("@opentelemetry/api");
25
+ /** Rule id recorded for denylist blocks (the worker reports them as their own signal). */
26
+ exports.DENYLIST = 'denylist';
27
+ const BODY_MAX = 64 * 1024;
28
+ let mode = 'monitor';
29
+ let compiled = [];
30
+ let denyIp = new Map();
31
+ let denyUser = new Map();
32
+ const expiryMap = (list) => new Map((list || []).map((e) => [e.value, e.expires_at ? e.expires_at * 1000 : Infinity]));
33
+ /** Replace the active ruleset (what the poller calls; tests may call it directly). */
34
+ function setRuleset(r) {
35
+ mode = r?.mode === 'block' ? 'block' : 'monitor';
36
+ compiled = [];
37
+ for (const rule of r?.rules || []) {
38
+ try {
39
+ compiled.push({ rule, re: new RegExp(rule.pattern, 'i') });
40
+ }
41
+ catch {
42
+ // not portable to JavaScript: skipped here, the worker still evaluates it
43
+ }
44
+ }
45
+ denyIp = expiryMap(r?.denylist?.ip);
46
+ denyUser = expiryMap(r?.denylist?.user);
47
+ }
48
+ const listed = (m, v, now) => !!v && (m.get(v) ?? 0) > now;
49
+ /** Whether `id` is on the user denylist (call after authentication to refuse a listed user). */
50
+ const isUserBlocked = (id, now = Date.now()) => listed(denyUser, id, now);
51
+ exports.isUserBlocked = isUserBlocked;
52
+ /** Judge one request. Denylisted callers are blocked in either mode. */
53
+ function inspect(req, now = Date.now()) {
54
+ if (listed(denyIp, req.ip, now) || listed(denyUser, req.user, now)) {
55
+ return { action: 'block', rule_id: exports.DENYLIST, category: 'abuse' };
56
+ }
57
+ for (const { rule, re } of compiled) {
58
+ for (const f of rule.fields) {
59
+ const v = req[f];
60
+ if (!v)
61
+ continue;
62
+ const m = re.exec(v);
63
+ if (m) {
64
+ return { action: mode === 'block' ? 'block' : 'monitor', rule_id: rule.id, category: rule.category, match: m[0].slice(0, 200) };
65
+ }
66
+ }
67
+ }
68
+ return { action: 'allow' };
69
+ }
70
+ const decode = (s, form = false) => {
71
+ const x = form ? s.replace(/\+/g, ' ') : s;
72
+ try {
73
+ return decodeURIComponent(x);
74
+ }
75
+ catch {
76
+ return x;
77
+ }
78
+ };
79
+ const first = (v) => (Array.isArray(v) ? v[0] : v);
80
+ /** Client IP: first `X-Forwarded-For` hop, else `X-Real-IP`, else the socket peer.
81
+ * shortcut: trusts the forwarding headers; run behind a proxy that overwrites them. */
82
+ function clientIp(req) {
83
+ const xff = first(req.headers?.['x-forwarded-for']);
84
+ if (xff)
85
+ return xff.split(',')[0].trim();
86
+ return first(req.headers?.['x-real-ip']) || req.socket?.remoteAddress?.replace(/^::ffff:/, '');
87
+ }
88
+ /** Decode a Node request into the inspector's fields. */
89
+ function fromNode(req, user) {
90
+ const url = req.originalUrl || req.url || '/';
91
+ const q = url.indexOf('?');
92
+ const headers = Object.entries(req.headers || {})
93
+ .filter(([k]) => k !== 'user-agent')
94
+ .map(([, v]) => (Array.isArray(v) ? v.join(', ') : v || ''))
95
+ .join('\n');
96
+ let body;
97
+ if (typeof req.body === 'string')
98
+ body = req.body.slice(0, BODY_MAX);
99
+ else if (req.body && typeof req.body === 'object') {
100
+ try {
101
+ body = JSON.stringify(req.body).slice(0, BODY_MAX);
102
+ }
103
+ catch {
104
+ body = undefined;
105
+ }
106
+ }
107
+ return {
108
+ path: decode(q < 0 ? url : url.slice(0, q)),
109
+ query: q < 0 ? '' : decode(url.slice(q + 1), true),
110
+ user_agent: first(req.headers?.['user-agent']) || '',
111
+ headers,
112
+ body,
113
+ ip: clientIp(req),
114
+ user,
115
+ };
116
+ }
117
+ /** Record a decision on the active span. */
118
+ function annotate(d, ip) {
119
+ const span = api_1.trace.getActiveSpan();
120
+ if (!span)
121
+ return;
122
+ if (ip)
123
+ span.setAttribute('appsec.client_ip', ip);
124
+ if (d.action === 'allow')
125
+ return;
126
+ span.setAttributes({
127
+ 'appsec.event': true,
128
+ 'appsec.rule_id': d.rule_id || '',
129
+ 'appsec.category': d.category || '',
130
+ 'appsec.blocked': d.action === 'block',
131
+ });
132
+ }
133
+ const PROBLEM = JSON.stringify({
134
+ type: 'about:blank',
135
+ title: 'Forbidden',
136
+ status: 403,
137
+ detail: 'Request blocked by Watchtower App and API Protection',
138
+ });
139
+ /** Inspect and, when blocked, answer 403. Returns true when the request was answered. */
140
+ function handleRequest(req, res, user) {
141
+ if (!compiled.length && !denyIp.size && !denyUser.size)
142
+ return false;
143
+ const r = fromNode(req, user);
144
+ const d = inspect(r);
145
+ annotate(d, r.ip);
146
+ if (d.action !== 'block')
147
+ return false;
148
+ res.statusCode = 403;
149
+ res.setHeader?.('content-type', 'application/problem+json');
150
+ res.end(PROBLEM);
151
+ return true;
152
+ }
153
+ /** Connect-style middleware; `user(req)` names the caller when the app already knows it. */
154
+ function appsecMiddleware(o = {}) {
155
+ return (req, res, next) => {
156
+ if (!handleRequest(req, res, o.user?.(req)))
157
+ next();
158
+ };
159
+ }
160
+ /** Mark the current request as a login attempt; failed ones feed the account-takeover rules. */
161
+ function trackLogin(login, success) {
162
+ const span = api_1.trace.getActiveSpan();
163
+ span?.setAttributes({ 'appsec.login': login, 'appsec.login.success': success });
164
+ if (success)
165
+ span?.setAttribute('appsec.auth', true);
166
+ }
167
+ /** Fetch the ruleset now and keep polling; `stop()` ends the polling. */
168
+ function startAppsec(o = {}) {
169
+ const env = process.env;
170
+ const base = (o.apiUrl || env.WT_API_URL || 'https://api.watchtower.dev').replace(/\/$/, '');
171
+ const key = o.key || env.WT_INGEST_KEY || '';
172
+ const service = o.service || env.WT_SERVICE || env.OTEL_SERVICE_NAME || 'unknown';
173
+ const f = o.fetch || globalThis.fetch;
174
+ let etag = '';
175
+ let timer;
176
+ let stopped = false;
177
+ let pollS = 30;
178
+ const poll = async () => {
179
+ try {
180
+ const res = await f(`${base}/v1/appsec/ruleset?service=${encodeURIComponent(service)}`, {
181
+ headers: { Authorization: `Bearer ${key}`, ...(etag ? { 'If-None-Match': etag } : {}) },
182
+ });
183
+ if (res.status === 200) {
184
+ const body = (await res.json());
185
+ setRuleset(body);
186
+ etag = res.headers.get('etag') || '';
187
+ pollS = Math.max(10, body.poll_s || 30);
188
+ }
189
+ }
190
+ catch {
191
+ // keep the last ruleset; try again on the next poll
192
+ }
193
+ if (!stopped) {
194
+ timer = setTimeout(() => void poll(), pollS * 1000);
195
+ timer.unref?.();
196
+ }
197
+ };
198
+ return {
199
+ ready: poll(),
200
+ stop() {
201
+ stopped = true;
202
+ if (timer)
203
+ clearTimeout(timer);
204
+ },
205
+ };
206
+ }
@@ -0,0 +1,27 @@
1
+ export interface IastOptions {
2
+ /** API base URL, e.g. `https://api.example.com`. */
3
+ apiUrl: string;
4
+ apiKey: string;
5
+ project: string;
6
+ service: string;
7
+ fetch?: typeof fetch;
8
+ /** Flush delay in ms (default 2000). */
9
+ flushMs?: number;
10
+ }
11
+ export interface TaintFinding {
12
+ vuln_type: string;
13
+ trace_id: string;
14
+ code_location: string;
15
+ severity: string;
16
+ title: string;
17
+ }
18
+ export declare function startIast(o: IastOptions): void;
19
+ export declare function stopIast(): void;
20
+ /** Express/Connect middleware: marks this request's inputs as tainted for downstream sinks. */
21
+ export declare function iastMiddleware(): (req: any, _res: unknown, next: (e?: unknown) => void) => void;
22
+ /** Check a sink's text against the current request's inputs; queue a finding on a hit. */
23
+ export declare function checkSink(vulnType: string, text: unknown, severity?: string): boolean;
24
+ /** Wrap a sink function whose first argument is the sensitive text (SQL, command, path, URL). */
25
+ export declare function guardSink<A extends unknown[], R>(fn: (...a: A) => R, vulnType: string): (...a: A) => R;
26
+ /** Send queued findings now. Never throws; a failed send drops the batch (IAST is best effort). */
27
+ export declare function flushIast(): Promise<void>;