securenow 8.0.3 → 8.2.0

package/NPM_README.md

@@ -259,8 +259,42 @@ npx securenow notifications read-all
 
 ### Alerting
 
+### Emit custom security events (new in 8.2)
+
+```js
+const { track } = require('securenow/events');
+
+// Fire-and-forget — batched, async, never throws into your app.
+track('auth.login.success', {
+  userId,            // enduser.id (durable identity for correlation)
+  sessionId,         // session.id
+  ip,                // end-user IP (enriched to geo/ASN server-side)
+  attributes: { method: 'magic_link', new_device: true },
+});
+```
+
+Events become queryable by alert rules immediately (`attributes_string['event.type']`, `['enduser.id']`, `['session.id']`, `['http.client_ip']`). Non-JS apps emit the same thing with a plain POST to `/v1/events`:
+
+```
+POST https://<your-ingest-host>/v1/events
+Authorization: Bearer snk_live_...
+X-SecureNow-App-Key: <app-uuid>
+
+{ "events": [ { "type": "auth.login.success", "user_id": "u_1", "session_id": "s_1", "ip": "1.2.3.4" } ] }
+```
+
+CLI: `npx securenow event send auth.login.failure --user u_1 --ip 1.2.3.4 --attrs reason=bad_token`
+
 ```bash
-# View alert rules, channels, and history
+# Create a custom detection rule from your own SQL (new in 8.1)
+npx securenow alerts rules create \
+  --name "Auth: magic-link brute force" \
+  --sql @rule.sql \
+  --apps <app-key> \
+  --severity high \
+  --nlp "single IP flooding /api/auth/signin or /api/auth/callback"
+
+# View / manage alert rules, channels, and history
 npx securenow alerts rules
 npx securenow alerts rules show <rule-id>
 npx securenow alerts rules update <rule-id> --applications-all
@@ -271,6 +305,8 @@ npx securenow alerts channels
 npx securenow alerts history --limit 20
 ```
 
+Your detection SQL scopes app keys with the `__USER_APP_KEYS__` placeholder and selects an `ip` column for per-IP aggregation and remediation. SecureNow stores the query, runs it on the rule's schedule (default every 15 min), and routes matches to your in-app channel (override with `--channel <id>`). Requires an API key with `alerts:write`.
+
 ### IP Intelligence & Blocklist
 
 ```bash