@chainpatrol/cli 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # @chainpatrol/cli
 
+## 0.20.0
+
+### Minor Changes
+
+- e63d269: Add `chainpatrol asset types` — list every supported `AssetType` enum
+  value with its human-readable label and a short description.
+
+  The mapping (e.g. `ARCHIVE_ORG` → "Archive.org" / Wayback snapshot,
+  `PAGE` → "Page" / standalone web page tracked independently of its
+  parent URL, `FIVE_HUNDRED_PX` → "500px") ships bundled with the CLI as
+  a static map, so the command works without auth or a network round
+  trip. Output is available in human, JSON, markdown, and CSV formats —
+  useful when an agent or script needs to translate enum ↔ display name,
+  validate a user-supplied `--asset-type` value, or enumerate the
+  available types before constructing a filter for `asset list`,
+  `threats list`, `takedowns list`, `detections list`, `reports list`,
+  or `orgs assets list`.
+
+  The Claude Code skill is updated to point at the new command whenever
+  a user asks "what is `ARCHIVE_ORG`?", "what does `PAGE` mean?", or
+  "what asset types does ChainPatrol support?". Shell completions and
+  top-level/per-command help text are updated accordingly.
+
+## 0.19.0
+
+### Minor Changes
+
+- 477a431: Add proper brand support across metrics and listings so agents can run a
+  real "trend search" on an org.
+
+  ## New: list brands for an org
+
+  `GET /organization/brands` (CLI: `chainpatrol brands list`) returns every
+  brand belonging to the caller's org — both parent / product brands
+  (`type: ORGANIZATION`) and individual / employee brands (`type:
+INDIVIDUAL`) — in one call. Soft-deleted brands are excluded. Use
+  `--type INDIVIDUAL` to filter to employee brands only. The endpoint is
+  org-scoped via auth, no extra args.
+
+  ## Fixed: brand filter actually applies on metrics
+
+  Two server-side bugs the trend-search docs ran into:
+
+  1. `GET /organization/metrics` with `brandSlug` was filtering the scalar
+     metrics (`reports`, `newThreats`, `takedownsFiled`, ...) but **not**
+     `blockedByType` / `blockedByDay`, which silently returned org-wide
+     totals. A caller drilling into a single brand would see "this brand
+     is being attacked on YouTube" when YouTube was really just an
+     org-wide trend.
+  2. `POST /metrics/breakdown` with `by: "brand"` was ignoring the
+     `brandIds` input filter — `getThreatsBlockedPerBrand()` always
+     returned every brand. The function now accepts `brandIds` and the
+     handler passes the input through.
+
+  Both are now wired through correctly. `metrics organization
+--brand-slug <slug> --include blockedByType,blockedByDay` returns
+  real brand-scoped time series, and `metrics breakdown --by brand
+--brand <id>` actually narrows to the requested brand(s).
+
+  ## Skill: full trend-search guide
+
+  Documents three trend signals the agent can answer from existing
+  commands, with concrete current-vs-baseline recipes:
+
+  1. Spike in a specific asset type (`metrics breakdown --by type`).
+  2. Spike in overall threat volume (`metrics breakdown --by day` +
+     `metrics organization`).
+  3. Spike on a specific sub-brand (`brands list` → join → `metrics
+breakdown --by brand` → `metrics organization --brand-slug`).
+     Employee vs. product distinction now comes straight from the brand
+     roster.
+
+  Server-side procedures + validation schemas live in the private
+  `@chainpatrol/external-trpc`, `@chainpatrol/validation`, and
+  `@chainpatrol/metrics` packages and ship together with this CLI
+  release, but are not listed in the frontmatter because they are
+  private.
+
 ## 0.18.0
 
 ### Minor Changes

package/dist/{breakdown-ETSF2BZ3.js → breakdown-3LJBT3JQ.js}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-VFT3TD3E.js";
 import {
   createApiClient
-} from "./chunk-DPLUSURP.js";
+} from "./chunk-O7TMOF4W.js";
 import "./chunk-EGWK6SRQ.js";
 import "./chunk-TFCNKBRC.js";
 import "./chunk-U73SABXK.js";

package/dist/{check-EMGFDXUO.js → check-G64UQCEL.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-VFT3TD3E.js";
 import {
   createApiClient
-} from "./chunk-DPLUSURP.js";
+} from "./chunk-O7TMOF4W.js";
 import "./chunk-EGWK6SRQ.js";
 import "./chunk-TFCNKBRC.js";
 import "./chunk-U73SABXK.js";

package/dist/{chunk-HGAQBGGL.js → chunk-2JZAPTY6.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-VFT3TD3E.js";
 import {
   createApiClient
-} from "./chunk-DPLUSURP.js";
+} from "./chunk-O7TMOF4W.js";
 import {
   DateTime
 } from "./chunk-TFCNKBRC.js";

package/dist/{chunk-MDDC4F6Q.js → chunk-3LJTWYT6.js}

@@ -1,7 +1,7 @@
 import {
   installCompletions,
   uninstallCompletions
-} from "./chunk-NQT77IB7.js";
+} from "./chunk-6VTWWGNV.js";
 
 // src/commands/setup-skill.ts
 import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, readFileSync as readFileSync3, rmSync } from "fs";
@@ -201,12 +201,23 @@ description: |
   "which customers have X enabled", "service toggles by org",
   "is this URL blocked", "is this domain blocked", "is this address blocked",
   "check this asset", "asset check", "lookup asset status",
+  "what is ARCHIVE_ORG", "what does PAGE mean", "list asset types",
+  "supported asset types", "asset type mapping", "asset type enum",
+  "what asset types are there", "human readable asset type",
   "how many takedowns", "takedowns in the last", "threats taken down",
   "across all clients", "across all customers", "across all orgs",
   "across all brands", "company-wide", "total takedowns", "total threats",
   "total reports", "average takedowns", "average threats", "average per day",
   "average per customer", "average per org", "rollup across customers",
-  "sum across orgs", "sum across customers".
+  "sum across orgs", "sum across customers",
+  "trends in org", "search for trends", "trend search", "look for trends",
+  "any trends", "trending threats", "spike in asset type",
+  "spike in threat volume", "coordinated attack", "spike check",
+  "anything unusual", "anything new for", "what's new for",
+  "employee being targeted", "spike on a sub-brand", "spike on a brand",
+  "sub-brand spike",
+  "list brands", "brands for org", "list sub-brands", "employee brands",
+  "individual brands", "brand list", "all brands in org".
 allowed-tools:
   - Bash
   - Read
@@ -375,6 +386,29 @@ If any individual lookup fails, the CLI still prints results for the
 successful ones, then exits non-zero so failures aren't silently
 swallowed.
 
+### \`asset types\` \u2014 List every supported asset type and what it means
+
+When a user asks "what is \`ARCHIVE_ORG\`?", "what does \`PAGE\` mean?",
+or "what asset types does ChainPatrol support?" \u2014 don't guess. Run:
+
+\`\`\`bash
+chainpatrol asset types
+chainpatrol --json asset types
+\`\`\`
+
+The mapping is bundled with the CLI (no API or auth required), so this
+is safe to run anywhere. Each row is \`{ type, label, description }\`:
+\`type\` is the canonical enum value used by every \`--asset-type\` flag
+(\`asset list\`, \`threats list\`, \`takedowns list\`, \`detections list\`,
+\`reports list\`, \`orgs assets list\`); \`label\` is the human-friendly
+display name (\`ARCHIVE_ORG\` \u2192 \`Archive.org\`, \`PAGE\` \u2192 \`Page\`,
+\`FIVE_HUNDRED_PX\` \u2192 \`500px\`); \`description\` is a one-line note for
+unobvious entries.
+
+Use this whenever you need to translate between enum and display name,
+validate that a type the user mentioned is real, or enumerate options
+before constructing a filter.
+
 ### \`configs list\` \u2014 List detection configurations
 
 Requires authentication and an organization slug.
@@ -732,6 +766,36 @@ takedowns?", reach for \`orgs list\` \u2014 it's the only command that exposes
 service flags across multiple orgs in one call. Run it in \`--json\` mode
 and summarize patterns by service or by subscription tier.
 
+### \`brands list\` \u2014 List the brands (sub-brands) belonging to an org
+
+Returns every brand for the org the caller is authenticated as, both
+parent / product brands (\`type: "ORGANIZATION"\`) and individual /
+employee brands (\`type: "INDIVIDUAL"\`). Soft-deleted brands are excluded.
+The endpoint is org-scoped and inferred from auth \u2014 there's no \`--org\`
+flag \u2014 so org-scoped API keys, user API keys, and user sessions all work
+without extra arguments.
+
+\`\`\`bash
+chainpatrol brands list                          # all brands
+chainpatrol brands list --type INDIVIDUAL        # employee / person brands only
+chainpatrol brands list --type ORGANIZATION      # product / parent brands only
+chainpatrol --json brands list                   # machine-readable
+\`\`\`
+
+Each entry has \`{ id, slug, name, type, description, brandGroupId, createdAt }\`.
+Use this when you need to:
+
+- Distinguish employee vs. product brands ahead of time \u2014 e.g. while
+  running a trend search and you want to highlight which spiking
+  sub-brands are employees so the user gets a direct heads-up to the
+  person involved.
+- Resolve a brand name the user mentions to its \`slug\` for use with
+  \`metrics organization --brand-slug <slug>\` or as a \`brandId\` for
+  \`takedowns list --brand <id>\`.
+- Audit a customer's setup \u2014 "how many employee brands does this org
+  protect?" or "are there brands the org set up but never wired into a
+  detection config?"
+
 ### \`metrics summary | found | breakdown | organization\` \u2014 Org metrics for spike/drop analysis
 
 #### Decision rule \u2014 read this before picking a metrics subcommand
@@ -1416,6 +1480,190 @@ Until a dedicated probe command exists:
 In both cases, if liveness looks miscalibrated for a class of assets,
 notify ChainPatrol engineering \u2014 the checker likely needs a tuning pass for
 that platform.
+
+## Organization Trend Search Guide
+
+Trend search asks "what's changed recently for this org?" \u2014 the answer can
+surface coordinated attacks, new attack channels, or campaigns targeting
+specific people, **before** they show up as a healthcheck failure. Unlike
+the HealthCheck Guide above (which grades single signals against
+thresholds), trend search compares a recent window to a baseline window
+and flags ratios, not absolute counts. A trend is interesting even when
+the pipeline is keeping up with it \u2014 the user usually wants to know.
+
+When the user asks something like:
+
+- "are there any trends in org X?"
+- "search for trends in <org>"
+- "anything unusual happening with <org> lately?"
+- "any spikes for <org>?"
+- "what's new for <org> this week?"
+- "is anyone targeting <org>'s employees more than usual?"
+- "are we seeing more YouTube/Telegram/etc. threats for <org>?"
+
+\u2026run the three trend checks below in parallel (single message, multiple
+Bash calls) and surface anything where the current rate is \u2265 2\xD7 the
+baseline AND clears a small absolute floor.
+
+### How to compute "current vs. baseline" rates
+
+Pick two non-overlapping windows: a **current** window the user cares about
+(default last 7 days) and a **baseline** window ending where the current
+one starts (default the prior ~90 days, i.e. \`current_start - 90d\` \u2192
+\`current_start - 1d\`). For any breakdown bucket, compute:
+
+\`\`\`
+current_per_day  = current_count  / current_window_days
+baseline_per_day = baseline_count / baseline_window_days
+ratio            = current_per_day / max(baseline_per_day, epsilon)
+\`\`\`
+
+Flag a bucket if \`ratio >= 2\` AND \`current_count >= 5\`. The floor
+suppresses noise on orgs with near-zero baseline activity (a single new
+YouTube report jumping the rate from 0 to 1/day shouldn't trigger). If
+the user gives a different window ("last 3 days", "this month"), adjust
+both windows proportionally and keep the same ratio threshold.
+
+### Trend 1 \u2014 Spike in a specific asset type
+
+A sudden jump in threats on a platform the org doesn't usually see
+traffic on ("normally you don't get targeted on YouTube much, but now
+there's a spike there") is worth flagging \u2014 it usually means an attacker
+has discovered a new channel that works for them. Even when the absolute
+number is small, the *ratio* against the org's normal mix is what
+matters.
+
+Use \`metrics breakdown --by type\` over both windows:
+
+\`\`\`bash
+# Current window \u2014 last 7 days, broken out by asset type
+chainpatrol --json metrics breakdown --org <slug> --by type \\
+  --from <YYYY-MM-DD 7d ago> --to <YYYY-MM-DD today>
+
+# Baseline window \u2014 prior ~90 days ending where the current window starts
+chainpatrol --json metrics breakdown --org <slug> --by type \\
+  --from <YYYY-MM-DD 97d ago> --to <YYYY-MM-DD 8d ago>
+\`\`\`
+
+Each entry in \`.points\` has \`{ type, count }\`. Join the two windows on
+\`type\`, apply the ratio rule above, and report each flagged type.
+
+Cross-reference any flagged type with \`configs list --org <slug>\` \u2014 if
+the spike is on Twitter / X but \`twitter_post_search\` is disabled, the
+detection source for that channel isn't even running for this org and
+the spike is being caught by something else (likely customer reports);
+suggest turning it on.
+
+### Trend 2 \u2014 Spike in overall threat volume
+
+A sharp rise in total threats across the org \u2014 regardless of type or
+brand \u2014 usually means a coordinated attack or campaign is underway. This
+isn't a healthcheck (reviewing and takedowns may be keeping up just
+fine), but the security team still wants to know so they can warn
+customers / employees / partners.
+
+\`\`\`bash
+# Daily volume for the last ~6 weeks \u2014 enough to eyeball a baseline AND
+# see the spike on the right edge of the series.
+chainpatrol --json metrics breakdown --org <slug> --by day \\
+  --from <YYYY-MM-DD 42d ago> --to <YYYY-MM-DD today>
+\`\`\`
+
+Read \`.points\` (one entry per day). Take the trailing 7-day average and
+compare against the prior ~5 weeks (the same 2\xD7 / floor rule). For round
+totals to quote to the user, also pull:
+
+\`\`\`bash
+# Two calls \u2014 current and baseline windows \u2014 using --include to skip
+# the per-type / per-day series and keep the call cheap.
+chainpatrol --json metrics organization --org <slug> \\
+  --include reports,newThreats,threatsWatchlisted \\
+  --from <current_from> --to <current_to>
+
+chainpatrol --json metrics organization --org <slug> \\
+  --include reports,newThreats,threatsWatchlisted \\
+  --from <baseline_from> --to <baseline_to>
+\`\`\`
+
+When volume spikes broadly, also skim \`reports list --reported-by-customer\`
+for the same window \u2014 a wave of customer reports often arrives a few hours
+ahead of automated detection on a real coordinated push.
+
+### Trend 3 \u2014 Spike on a specific sub-brand (especially employee brands)
+
+Sub-brands the org has set up for individual people \u2014 employees,
+executives, public figures \u2014 are high-signal targets. A sudden spike on
+one usually means an attacker is impersonating that person specifically,
+which is materially different from a generic phishing wave and usually
+warrants a direct heads-up to the person involved. In the database these
+are \`Brand\` rows with \`type: INDIVIDUAL\` (vs. \`ORGANIZATION\` for
+product / parent brands).
+
+**Step 1: Pull the brand roster** so you can label each spike as
+"employee" or "product" without asking the user.
+
+\`\`\`bash
+chainpatrol --json brands list
+\`\`\`
+
+Build a map of \`slug \u2192 type\` from the response so the next step's
+findings can be tagged \`(employee)\` or \`(product)\` automatically.
+
+**Step 2: Run the breakdown over both windows.**
+
+\`\`\`bash
+# Current window \u2014 last 7 days, broken out by sub-brand
+chainpatrol --json metrics breakdown --org <slug> --by brand \\
+  --from <YYYY-MM-DD 7d ago> --to <YYYY-MM-DD today>
+
+# Baseline window \u2014 prior ~90 days
+chainpatrol --json metrics breakdown --org <slug> --by brand \\
+  --from <YYYY-MM-DD 97d ago> --to <YYYY-MM-DD 8d ago>
+\`\`\`
+
+Each entry in \`.points\` has \`{ brandId, brandSlug, brandName, count }\`.
+Apply the ratio rule, join against the \`slug \u2192 type\` map from Step 1,
+and report each spiking sub-brand by name plus its type.
+
+**Step 3: Drill into the flagged brand** with \`metrics organization
+--brand-slug <slug>\` for a per-day / per-type breakdown scoped to that
+brand only. The server applies the brand filter to the scalar metrics
+(\`newThreats\`, \`takedownsFiled\`, etc.) AND to \`blockedByType\` /
+\`blockedByDay\`, so the time series and per-asset-type counts are real
+brand-only data:
+
+\`\`\`bash
+chainpatrol --json metrics organization --org <slug> \\
+  --brand-slug <brand-slug> \\
+  --include newThreats,blockedByType,blockedByDay \\
+  --from <YYYY-MM-DD 7d ago> --to <YYYY-MM-DD today>
+\`\`\`
+
+If multiple \`INDIVIDUAL\` brands are spiking at the same time, treat that
+as a stronger signal than a single one \u2014 likely a campaign targeting the
+company's people rather than a single impersonation. Prioritize those
+findings over single-brand spikes when summarizing.
+
+### Reporting trend findings
+
+Report each spiking bucket as its own finding with: the trend it falls
+under (asset type / overall volume / sub-brand), the current vs. baseline
+rate (e.g. "youtube: 12/day last 7d vs. 1.2/day prior 90d, \xD710
+baseline"), and a one-line follow-up:
+
+- Asset-type spike \u2192 check \`configs list\` for the matching detection
+  source and turn it on if it's off.
+- Overall-volume spike \u2192 flag a possible coordinated campaign; suggest
+  the security team look at the recent \`reports list\` for shared
+  infrastructure (sender, registrar, hosting).
+- Sub-brand spike \u2192 look up \`type\` via \`brands list\`; if
+  \`INDIVIDUAL\`, suggest a direct heads-up to that person; if
+  \`ORGANIZATION\`, suggest a product-team alert.
+
+If none of the three trends fire above the 2\xD7 / floor thresholds, say so
+explicitly ("no significant trends in the last 7 days vs. the prior 90")
+rather than dumping every breakdown number \u2014 the absence is the
+finding.
 `;
 }
 function getBundledSkillVersion() {

package/dist/{chunk-NQT77IB7.js → chunk-6VTWWGNV.js}

@@ -66,6 +66,7 @@ _chainpatrol() {
         asset_subcommands=(
           'check:Check asset status against ChainPatrol'
           'list:List assets in the global ChainPatrol blocklist'
+          'types:List supported asset types and their human-readable labels'
         )
         _describe 'subcommand' asset_subcommands
         ;;
@@ -161,7 +162,7 @@ var BASH_COMPLETION = `_chainpatrol() {
       return 0
       ;;
     asset)
-      COMPREPLY=( $(compgen -W "check list" -- "\${cur}") )
+      COMPREPLY=( $(compgen -W "check list types" -- "\${cur}") )
       return 0
       ;;
     configs)

package/dist/{chunk-DPLUSURP.js → chunk-O7TMOF4W.js}

@@ -392,6 +392,9 @@ function createApiClient(options) {
         {}
       );
     },
+    listOrganizationBrands() {
+      return requestGet("/organization/brands", {});
+    },
     getCurrentUser() {
       return request("/user/me", {});
     },