securenow 8.8.0 → 8.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securenow",
-  "version": "8.8.0",
+  "version": "8.10.0",
   "description": "OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt - Send traces and logs to any OTLP-compatible backend",
   "type": "commonjs",
   "main": "register.js",
@@ -50,10 +50,14 @@
       "types": "./tracing.d.ts",
       "default": "./tracing.js"
     },
-    "./events": {
-      "types": "./events.d.ts",
-      "default": "./events.js"
-    },
+    "./events": {
+      "types": "./events.d.ts",
+      "default": "./events.js"
+    },
+    "./telemetry-schema": {
+      "types": "./telemetry-schema.d.ts",
+      "default": "./telemetry-schema.js"
+    },
     "./sessions": {
       "types": "./sessions.d.ts",
       "default": "./sessions.js"
@@ -123,8 +127,11 @@
     "register.d.ts",
     "tracing.js",
     "tracing.d.ts",
-    "events.js",
-    "events.d.ts",
+    "events.js",
+    "events.d.ts",
+    "telemetry-schema.js",
+    "telemetry-schema.d.ts",
+    "telemetry-schema.json",
     "sessions.js",
     "sessions.d.ts",
     "console-instrumentation.js",
@@ -159,34 +166,35 @@
     "web-vite.mjs",
     "app-config.js",
     "README.md",
-    "NPM_README.md",
+    "NPM_README.md",
+    "TELEMETRY-SQL.md",
     "SKILL-CLI.md",
     "SKILL-API.md"
   ],
   "dependencies": {
     "@opentelemetry/api": ">=1.9.0 <1.10.0",
-    "@opentelemetry/api-logs": "0.218.0",
-    "@opentelemetry/auto-instrumentations-node": "0.76.0",
-    "@opentelemetry/core": "2.7.1",
-    "@opentelemetry/exporter-logs-otlp-http": "0.218.0",
-    "@opentelemetry/exporter-trace-otlp-http": "0.218.0",
-    "@opentelemetry/instrumentation": "0.218.0",
-    "@opentelemetry/instrumentation-document-load": "0.63.0",
-    "@opentelemetry/instrumentation-fetch": "0.218.0",
-    "@opentelemetry/instrumentation-http": "0.218.0",
-    "@opentelemetry/instrumentation-mongodb": "0.71.0",
-    "@opentelemetry/instrumentation-user-interaction": "0.62.0",
-    "@opentelemetry/instrumentation-xml-http-request": "0.218.0",
-    "@opentelemetry/resources": "2.7.1",
-    "@opentelemetry/sdk-logs": "0.218.0",
-    "@opentelemetry/sdk-metrics": "2.7.1",
-    "@opentelemetry/sdk-node": "0.218.0",
-    "@opentelemetry/sdk-trace-base": "2.7.1",
-    "@opentelemetry/sdk-trace-web": "2.7.1",
-    "@opentelemetry/semantic-conventions": "1.41.1"
+    "@opentelemetry/api-logs": "0.220.0",
+    "@opentelemetry/auto-instrumentations-node": "0.78.0",
+    "@opentelemetry/core": "2.9.0",
+    "@opentelemetry/exporter-logs-otlp-http": "0.220.0",
+    "@opentelemetry/exporter-trace-otlp-http": "0.220.0",
+    "@opentelemetry/instrumentation": "0.220.0",
+    "@opentelemetry/instrumentation-document-load": "0.65.0",
+    "@opentelemetry/instrumentation-fetch": "0.220.0",
+    "@opentelemetry/instrumentation-http": "0.220.0",
+    "@opentelemetry/instrumentation-mongodb": "0.73.0",
+    "@opentelemetry/instrumentation-user-interaction": "0.64.0",
+    "@opentelemetry/instrumentation-xml-http-request": "0.220.0",
+    "@opentelemetry/resources": "2.9.0",
+    "@opentelemetry/sdk-logs": "0.220.0",
+    "@opentelemetry/sdk-metrics": "2.9.0",
+    "@opentelemetry/sdk-node": "0.220.0",
+    "@opentelemetry/sdk-trace-base": "2.9.0",
+    "@opentelemetry/sdk-trace-web": "2.9.0",
+    "@opentelemetry/semantic-conventions": "1.43.0"
   },
   "optionalDependencies": {
-    "@vercel/otel": "2.1.2"
+    "@vercel/otel": "2.1.3"
   },
   "sideEffects": true,
   "license": "ISC"

package/telemetry-schema.d.ts

@@ -0,0 +1,16 @@
+export interface SecureNowTelemetrySchema {
+  contract: string;
+  schemaVersion: string;
+  dialect: 'ClickHouse';
+  purpose: string;
+  ruleContract: Record<string, unknown>;
+  tables: Record<string, unknown>;
+  clientIp: Record<string, unknown>;
+  customEvents: Record<string, unknown>;
+  automaticTraceFields: Record<string, string[]>;
+  templates: Record<string, string>;
+  authoringWorkflow: string[];
+}
+
+declare const schema: SecureNowTelemetrySchema;
+export = schema;

package/telemetry-schema.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./telemetry-schema.json');

package/telemetry-schema.json

@@ -0,0 +1,188 @@
+{
+  "contract": "securenow.telemetry.alert-sql",
+  "schemaVersion": "1.0.0",
+  "dialect": "ClickHouse",
+  "purpose": "Canonical local contract for agents and humans authoring SecureNow alert rules.",
+  "ruleContract": {
+    "tenantPlaceholder": "__USER_APP_KEYS__",
+    "requiredResultColumns": [
+      {
+        "name": "ip",
+        "type": "String",
+        "reason": "Per-IP grouping and IP-based remediation use this column. Keep empty IPs out of the final result."
+      }
+    ],
+    "requirements": [
+      "Query only documented telemetry tables and fields.",
+      "Keep __USER_APP_KEYS__ in every customer-scoped query.",
+      "Use the tenant expression documented for the selected table.",
+      "Return an ip column and exclude empty IP values for IP-remediation rules.",
+      "Bound every query with a time window.",
+      "Validate candidate SQL before creating or updating a rule.",
+      "Treat fields absent from live field discovery as unverified until instrumentation emits them."
+    ]
+  },
+  "tables": {
+    "logs": {
+      "name": "signoz_logs.distributed_logs_v2",
+      "purpose": "OpenTelemetry logs and SecureNow custom security events.",
+      "timestamp": {
+        "column": "timestamp",
+        "type": "UInt64",
+        "unit": "nanoseconds",
+        "timeFilterExample": "timestamp >= toUnixTimestamp64Nano(now64() - INTERVAL 15 MINUTE)"
+      },
+      "tenantExpression": "resources_string['service.name'] IN (__USER_APP_KEYS__)",
+      "columns": {
+        "timestamp": "UInt64 nanoseconds",
+        "observed_timestamp": "UInt64 nanoseconds",
+        "id": "String",
+        "trace_id": "String",
+        "span_id": "String",
+        "severity_text": "LowCardinality(String)",
+        "severity_number": "UInt8",
+        "body": "String",
+        "attributes_string": "Map(String, String)",
+        "attributes_number": "Map(String, Float64)",
+        "attributes_bool": "Map(String, Bool)",
+        "resources_string": "Map(String, String)",
+        "scope_name": "String",
+        "scope_version": "String"
+      },
+      "mapAccess": {
+        "string": "attributes_string['field.name']",
+        "number": "attributes_number['field.name']",
+        "boolean": "attributes_bool['field.name']",
+        "resource": "resources_string['field.name']"
+      }
+    },
+    "traces": {
+      "name": "signoz_traces.distributed_signoz_index_v3",
+      "purpose": "OpenTelemetry spans including automatically captured HTTP request telemetry.",
+      "timestamp": {
+        "column": "timestamp",
+        "type": "DateTime64(9)",
+        "unit": "nanoseconds precision",
+        "timeFilterExample": "timestamp >= now64(9) - INTERVAL 15 MINUTE"
+      },
+      "tenantExpression": "`resource_string_service$$name` IN (__USER_APP_KEYS__)",
+      "columns": {
+        "timestamp": "DateTime64(9)",
+        "trace_id": "FixedString(32)",
+        "span_id": "String",
+        "parent_span_id": "String",
+        "name": "LowCardinality(String)",
+        "kind": "Int8 (1 internal, 2 server, 3 client, 4 producer, 5 consumer)",
+        "duration_nano": "UInt64",
+        "status_code": "Int16",
+        "status_message": "String",
+        "attributes_string": "Map(String, String)",
+        "attributes_number": "Map(String, Float64)",
+        "attributes_bool": "Map(String, Bool)",
+        "resources_string": "Map(String, String)",
+        "response_status_code": "LowCardinality(String)",
+        "http_url": "LowCardinality(String)",
+        "http_method": "LowCardinality(String)",
+        "http_host": "LowCardinality(String)",
+        "has_error": "Bool",
+        "resource_string_service$$name": "LowCardinality(String)",
+        "attribute_string_http$$route": "LowCardinality(String)"
+      },
+      "mapAccess": {
+        "string": "attributes_string['field.name']",
+        "number": "attributes_number['field.name']",
+        "boolean": "attributes_bool['field.name']",
+        "resource": "resources_string['field.name']"
+      }
+    }
+  },
+  "clientIp": {
+    "preferredField": "http.client_ip",
+    "traceExpression": "coalesce(nullIf(attributes_string['http.client_ip'], ''), nullIf(attributes_string['net.peer.ip'], ''), nullIf(attributes_string['network.peer.address'], ''), nullIf(attributes_string['client.address'], ''), nullIf(attributes_string['net.sock.peer.addr'], ''))",
+    "eventExpression": "attributes_string['http.client_ip']",
+    "trustNote": "Confirm trusted-proxy configuration before using forwarded IPs for blocking."
+  },
+  "customEvents": {
+    "sdkImport": "securenow/events",
+    "signature": "track(type: string, props?: TrackProps): void",
+    "storageTable": "logs",
+    "propertyMapping": {
+      "type": "attributes_string['event.type']",
+      "userId": "attributes_string['enduser.id']",
+      "sessionId": "attributes_string['session.id']",
+      "ip": "attributes_string['http.client_ip']",
+      "userAgent": "attributes_string['http.user_agent']",
+      "severity": "severity_text",
+      "attributes.string": "attributes_string['<custom-key>']",
+      "attributes.number": "attributes_number['<custom-key>']",
+      "attributes.boolean": "attributes_bool['<custom-key>']"
+    },
+    "recommendedAuthenticationEvents": [
+      "auth.login.failure",
+      "auth.login.success",
+      "auth.otp.send.requested",
+      "auth.otp.send.result",
+      "auth.otp.verify.failure",
+      "auth.otp.verify.success",
+      "auth.password_reset.requested",
+      "auth.password_reset.completed",
+      "auth.mfa.challenge.failure",
+      "auth.mfa.challenge.success",
+      "auth.session.revoked"
+    ]
+  },
+  "automaticTraceFields": {
+    "http": [
+      "http.method",
+      "http.route",
+      "http.target",
+      "http.url",
+      "http.status_code",
+      "http.host",
+      "http.scheme",
+      "http.user_agent"
+    ],
+    "clientAndProxy": [
+      "http.client_ip",
+      "http.client_ip.source",
+      "http.socket_ip",
+      "http.forwarded_for",
+      "http.real_ip",
+      "http.cf.connecting_ip",
+      "http.proxy.trusted"
+    ],
+    "securityPresenceOnly": [
+      "http.security.auth_present",
+      "http.security.cookies_present",
+      "http.security.csrf_token_present"
+    ],
+    "optionalBodyCapture": [
+      "http.request.body",
+      "http.request.body.type",
+      "http.request.body.size",
+      "http.request.body.parse_error"
+    ],
+    "resources": [
+      "service.name",
+      "service.instance.id",
+      "service.version",
+      "deployment.environment",
+      "telemetry.sdk.name",
+      "telemetry.sdk.language",
+      "telemetry.sdk.version"
+    ]
+  },
+  "templates": {
+    "traceBurstByIp": "WITH coalesce(nullIf(attributes_string['http.client_ip'], ''), nullIf(attributes_string['net.peer.ip'], ''), nullIf(attributes_string['network.peer.address'], ''), nullIf(attributes_string['client.address'], ''), nullIf(attributes_string['net.sock.peer.addr'], '')) AS client_ip\nSELECT client_ip AS ip, count() AS hits\nFROM signoz_traces.distributed_signoz_index_v3\nWHERE `resource_string_service$$name` IN (__USER_APP_KEYS__)\n  AND timestamp >= now64(9) - INTERVAL 15 MINUTE\n  AND attributes_string['http.target'] = '/replace-with-real-route'\nGROUP BY ip\nHAVING ip != '' AND hits >= 20",
+    "eventFailuresByIp": "SELECT attributes_string['http.client_ip'] AS ip, count() AS failures\nFROM signoz_logs.distributed_logs_v2\nWHERE resources_string['service.name'] IN (__USER_APP_KEYS__)\n  AND timestamp >= toUnixTimestamp64Nano(now64() - INTERVAL 15 MINUTE)\n  AND attributes_string['event.type'] = 'replace.with.verified.event'\nGROUP BY ip\nHAVING ip != '' AND failures >= 10"
+  },
+  "authoringWorkflow": [
+    "npx securenow telemetry schema --json",
+    "npx securenow telemetry fields --app <key> --env production --since 24h --json",
+    "npx securenow alerts rules --json",
+    "npx securenow alerts rules validate --sql @rule.sql --app <key>",
+    "npx securenow alerts rules create --name <name> --sql @rule.sql --apps <key>",
+    "npx securenow alerts rules test <rule-id> --mode dry_run --wait",
+    "npx securenow alerts rules promote <rule-id>"
+  ]
+}