censys-timeline
Use when the user wants temporal analysis of how a Censys-tracked asset changed over time — e.g. "censys timeline," "censys host history," "censys what changed on this host," "censys when did this service appear," "censys change detection," "censys temporal analysis," "censys track cert rotations," or "censys did this host change hands." Wraps `censys history` for hosts, web properties, and certificates. Not for current-state lookups (see censys-view) or criteria search (see censys-search).
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-30
- Stars
- ★ 14
- Forks
- 0
01 前言 Front Matter
- name
- censys-timeline
- version
- 0.1.0
- description
- Use when the user wants temporal analysis of how a Censys-tracked asset changed over time — e.g. "censys timeline," "censys host history," "censys what changed on this host," "censys when did this service appear," "censys change detection," "censys temporal analysis," "censys track cert rotations," or "censys did this host change hands." Wraps `censys history` for hosts, web properties, and certificates. Not for current-state lookups (see censys-view) or criteria search (see censys-search).
02 资源文件 1
- 参考文档references/cli-globals.md1.9 KB
03 SKILL.md 正文
censys-timeline
When to use
Use this skill when the user wants to understand how an asset changed across a window of time, rather than its current state. Typical asks:
- "censys timeline for 8.8.8.8"
- "censys host history — what changed on this box last month"
- "censys when did port 8443 first appear on this IP"
- "censys change detection over the last 90 days"
- "censys temporal analysis of this web property"
- "did this host change hands, per censys"
Do not use this for a single point-in-time lookup (censys-view), for
criteria-based search (censys-search), or for post-retrieval jq/SQLite recipes
on data you already have (censys-analyze, which this skill hands off to once
timeline JSON is pulled). This skill covers pulling and interpreting censys history output specifically.
Invocation
censys history <asset> [flags]
<asset> type is auto-detected, same rules as censys view:
| Input pattern | Resolved as |
|---|---|
IP address (e.g. 8.8.8.8) |
Host |
hostname:port |
Web property |
| 64-character hex string | Certificate (SHA-256 fingerprint) — requires Threat Hunting module access |
Skill-specific flags
| Flag | Purpose |
|---|---|
--duration, -d <window> |
Time window ending now, e.g. 24h, 7d (default), 4w, 1y |
--start, -s <RFC3339> |
Absolute window start |
--end, -e <RFC3339> |
Absolute window end |
--start/--end and --duration compose (per CLI help examples):
| Flags given | Window |
|---|---|
--duration only |
now − duration → now |
--start + --duration |
start → start + duration |
--end + --duration |
end − duration → end |
--start + --end |
exact window; --duration ignored if also passed |
Global CLI flags
See ${CLAUDE_SKILL_DIR}/references/cli-globals.md for the full global flags reference (output
format, streaming, diagnostics, org-id, and PAT vs OAuth notes). Note:
history does not support -O short or -O template (exit code 2).
Event model
A host timeline is a sequence of discrete events, each with an event_time and
a typed payload key. Treat the timeline as a diff stream, not a series of full
snapshots — each event describes what changed, not the whole host state at that
moment.
Event types and their JSON structure
Each event has event_time plus exactly one of these payload keys (verified against cencli 1.1.3 output, 2026-08):
| Payload key | What it captures | Protocol field |
|---|---|---|
endpoint_scanned |
HTTP/banner-level observation (headers, body, HTML title) | .endpoint_scanned.scan.endpoint_type |
service_scanned |
Service-level observation (TLS, SSH, RDP, protocol ID) | .service_scanned.scan.protocol |
jarm_scanned |
JARM fingerprint observation | .jarm_scanned.scan.fingerprint |
forward_dns_resolved |
DNS A/AAAA resolution change | — |
reverse_dns_resolved |
Reverse DNS (PTR) change | — |
whois_updated |
WHOIS registration change | — |
Note that endpoint_scanned and service_scanned use different field names for the protocol (endpoint_type vs protocol). A single port can produce both event types, and can show multiple protocols (e.g. port 8888 responding as both HTTP and DVR_IP depending on the probe).
Semantic categories
Use event types to classify changes:
- Service events (
service_scanned) — a port opened, closed, or its transport/application protocol changed. - Endpoint events (
endpoint_scanned) — theServerheader, raw banner, HTML title, or other application-layer text changed. - Certificate events (
service_scannedwith.tls) — the TLS certificate rotated. Note: cert fingerprint lives at.service_scanned.scan.tls.fingerprint_sha256(an extra.scanlevel compared tocensys viewoutput). - Infrastructure events (
whois_updated, DNS events) — the announcing AS changed, WHOIS registration updated, or DNS resolution shifted.
Common patterns
# Last 30 days — always save to file for reuse across jq passes
censys history 8.8.8.8 --duration 30d -O json > data/timeline.json
# Bounded window for incident investigation
censys history 8.8.8.8 --start <start-date> --end <end-date> -O json
# Web property history
censys history example.com:443 --duration 14d -O json
# Certificate observation history (Threat Hunting module required)
censys history <sha256> --start <start-date> --end <end-date>
# Stream events as NDJSON instead of buffering a full array
censys history 8.8.8.8 --duration 90d -S
Temporal analysis with jq
# When did a specific port first appear?
jq '[.[] | select(.service_scanned.scan.port == 8443) | .event_time] | sort | .[0]' \
data/timeline.json
# Track cert rotations over time (unique leaf fingerprints in order)
jq '[.[] | .service_scanned.scan.tls.fingerprint_sha256 // empty |
{cert: .}] | unique_by(.cert)' data/timeline.json
# Find all service-level changes, chronologically
jq '[.[] | select(.service_scanned) | {time: .event_time,
port: .service_scanned.scan.port,
protocol: .service_scanned.scan.protocol}] | sort_by(.time)' \
data/timeline.json
# Compare host state at two points in time (snapshot diff, not history events)
censys view 203.0.113.50 --at-time <past-date> -O json > data/before.json
censys view 203.0.113.50 -O json > data/after.json
diff <(jq -S '.[0].services | sort_by(.port)' data/before.json) \
<(jq -S '.[0].services | sort_by(.port)' data/after.json)
For anything beyond these direct lookups — cross-referencing multiple hosts'
timelines, loading into SQLite for aggregation, batch cert analysis — hand off
to censys-analyze once the timeline JSON is on disk.
Change detection workflow
- Pull history with a wide window:
censys history <ip> --duration 90d -O json > data/timeline.json. - Extract event timestamps and types with jq (see patterns above) to build a chronological list of what changed and when.
- Look for clusters — multiple distinct event types (e.g. new cert + new SSH key + new open ports) landing within the same short window. A cluster across independent signals is a much stronger change signal than any single event in isolation.
- For each cluster, snapshot before and after with
censys view --at-timebracketing the cluster's start and end. - Diff the before/after snapshots (see the
diffpattern above) to pin down exactly what changed, rather than inferring it from event summaries alone.
Interpreting timeline data
- Routine, low signal — certificate renewals on a roughly 90-day cycle (Let's Encrypt and similar ACME issuers), minor banner version bumps, transient port flaps. Expected background noise on any long-lived host.
- Significant, worth flagging — SSH host key rotation, several services appearing or disappearing at the same time, an AS number change, or a wholesale change of certificate issuer (e.g. a self-signed cert replacing a publicly-trusted one, or vice versa).
- Attribution boundaries — when a cluster of simultaneous changes lines up (new SSH host key + new certificates + new service set appearing together), treat that cluster as a probable operator/tenant boundary. Activity observed before the cluster and activity observed after it may belong to different actors entirely — don't attribute both sides of the boundary to the same operator without corroborating evidence.
- Service lifecycle — a service that has been present across the entire
queried window is "normal" for that host. A service that first appears
partway through the window (especially one atypical for the host's apparent
role) is a candidate for new deployment or compromise, and warrants closer
inspection of what else changed around the same
event_time.
Performance characteristics
History volume depends heavily on the host and time window. A busy, well-scanned host can produce thousands of events per day — measured: 8.8.8.8 returned 2,621 events for a single day (measured on cencli 1.1.3, 2026-08).
Always use streaming (-S) for history pulls. Buffered output (-O json
without -S) loads the entire result into memory before writing anything.
On a large history this can take minutes or never complete. Streaming emits
events as they arrive and completes in a fraction of the time.
For bulk history pulls across many hosts:
- Start narrow. Use
--duration 7dor--duration 30dto confirm the signal is there before widening. A 1-year pull on an active host can produce hundreds of thousands of events. - Chunk into batches of 3–5 with extended timeouts (300s+) if doing
sequential pulls. Save each result to
data/as it completes. - Budget time generously. Even with streaming, a 90-day pull on an active host can take 60–180 seconds.
Parsing CLI output programmatically
When redirecting censys history -O json to a file and parsing it later:
- stdout is valid JSON. The output (when using
-O json) is a single JSON array starting on the first line. Parse it directly — no line-skipping needed. The status line goes to stderr and-qsuppresses it. - Empty results may be
null. Some hosts returnnullinstead of[]for zero events. Defensive parsing:data = json.load(f) or []. - Large outputs. A 3000-event history can be several MB of JSON. For
repeated analysis passes, save to disk and use
jqor load into a Python dict once rather than re-pulling.
Error handling
| Error | Cause | Resolution |
|---|---|---|
| Exit code 2, unsupported format | -O short or -O template passed to history |
Use json, yaml, or tree instead |
[Threat Hunting Required] (or similar entitlement error) |
Certificate history requested without Threat Hunting module access | Confirm module entitlement, or fall back to host/web-property history if the cert itself isn't the actual target |
| Slow response / rate limited | Window too wide (e.g. 1y) or too many concurrent history pulls |
Start with --duration 7d, confirm the signal is there, then widen incrementally rather than jumping straight to a multi-year pull. See Performance characteristics above for expected times. |
| Empty result set | No events in the requested window | Widen the window, or confirm the asset had any Censys-observed activity at all via censys view first |
Caveats
-
History events are diffs against the prior observed state, not full snapshots — don't assume every field is repeated on every event. Use
censys view --at-timewhen a complete point-in-time record is needed. -
Wide time windows are slow and count more heavily against rate limits. Widen incrementally (
7d→30d→90d) rather than defaulting to a large window. -
GeoIP/location events reflect registry and geolocation data, which can lag or be imprecise — corroborate an apparent "location change" with the accompanying AS change before treating it as a strong reassignment signal.
-
Labels and event classifications are Censys-derived heuristics; treat them as triage aids, not ground truth, especially for attribution calls.
-
A port can be absent from the whole event stream and still be open. The history stream does not always cover every port on a host. A port can produce zero events across a full year — no success events and no failure events — while
censys viewshows the same port scanned on the same day, with a complete banner. Absence of events is not evidence that the service was down or intermittent.Confirm coverage before you make any claim about when a service started, stopped, or flapped:
# ports present in the history stream jq -r '[.[].service_scanned.scan.port] | unique' history.json # ports open right now jq -r '[.[0].services[].port] | sort' view.jsonIf a port is in the second list but not the first, the history stream does not cover that port. State this as an instrumentation gap. Two consequences follow:
- First-seen dates from history are a lower bound, and they are anchored only to the ports the stream does cover.
- Do not report the gap as intermittent service. A real case: ports 8085–8087 produced zero events across one year on five of six C2 hosts, while the current snapshot showed all three ports scanned that morning. Reading the gap as intermittent C2 would have been a false finding.
Cross-references
- For a single point-in-time snapshot (including
--at-timeon a specific date), seecensys-view. - For post-retrieval analysis of saved timeline JSON — jq recipes, SQLite
loading, batch cert correlation, cross-referencing multiple assets — see
censys-analyze. - For the broader investigation workflow this fits into, see
censys-investigate.
04 同仓库更多 Skills
censys-view
Use when the user wants detailed point-lookup data on a single asset via the Censys CLI — e.g. "censys view," "censys look up this IP," "censys host details for," "view this cert on censys," "censys what services does X run," "censys view this cert," "look this host up on censys," "censys pull the record for," "what does censys show for this hostname," "what's running on this IP," "profile this host," or "show me this host's services." Wraps `censys view` for hosts, certificates, and web properties. This is the right skill for any single-asset lookup — use censys-investigate only when the user explicitly asks for a multi-step investigation. Not for search-by-criteria (see censys-search) or time-series history (see censys-timeline).
censys-search
Use when the user wants to run a censys search, censys search for hosts or certificates, search censys for hosts/certs/web properties, find censys hosts with a given condition, run a censys query for hosts, or search for certificates on censys using CenQL. Wraps the `censys search` CLI subcommand. Trigger phrases include "censys search," "search censys for," "find censys hosts with," "censys query for hosts," and "search for certificates on censys." Do not use for viewing a single known host/cert/domain by identifier (see censys-view) or for aggregating/counting by field (see censys-aggregate).
censys-investigate
Use when the user explicitly requests a multi-step Censys investigation — e.g. "censys investigate," "censys deep dive into," "trace this infrastructure with censys," "censys pivot chain," "full censys investigation," "hunt for related infrastructure," or "/censys-investigate." This is a heavyweight methodology skill (typically 20–50+ API calls) — do NOT fire on simple lookups like "what's running on this IP" or "profile this host" (use censys-view for those). Structured as a baseline collection phase followed by decision trees that branch on what the baseline reveals. Prescribes a findings template and data preservation convention. Always confirms scope and estimated cost with the user before starting.
censys-enrich
Use when the user wants fast, credit-free IP context for SOC/triage work via the Censys CLI — e.g. "censys enrich," "censys enrich this IP," "censys bulk enrich," "censys triage IP," "censys SOC lookup," "is this IP interesting per censys," "censys check this IP for scanning activity," or "censys reputation on this address." Wraps `censys enrich` for single/bulk IP enrichment (location, AS, WHOIS, DNS, labels, GreyNoise, reputation, network/privacy classification, third-party verdicts). Not for full host records with all services and raw banners (see censys-view) or criteria-based search (see censys-search).
censys-censeye
Use when the user wants to run censys censeye, censys pivot analysis, censys rarity analysis, censys find related infrastructure, or run censeye on a host. Wraps the `censys censeye` CLI subcommand to analyze a single host and generate pivotable threat-hunting queries bounded by rarity (how many other hosts share each attribute). Trigger phrases include "censys censeye," "censys pivot analysis," "censys rarity analysis," "censys find related infrastructure," and "run censeye on." Requires Threat Hunting feature access on the organization. Not for criteria-based search (see censys-search) or single-record point lookups (see censys-view).
censys-cenql
Use when the user needs help with CenQL syntax, censys query syntax, how to write a censys query, what censys fields are available, or censys query help — field paths, operators, quoting/escaping rules, or example queries for hosts, certificates, and web properties. Trigger phrases include "CenQL syntax," "censys query syntax," "how do I write a censys query," "what censys fields are available," and "censys query help." Also fires when the user writes "CQL," a frequent misspelling of CenQL. This is a reference skill, not a CLI wrapper — defer to censys-search, censys-aggregate, or censys-view to actually execute the query once it's constructed.