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.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-30
- Stars
- ★ 14
- Forks
- 0
01 前言 Front Matter
- name
- censys-cenql
- version
- 0.3.0
- description
- 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.
02 资源文件 2
- 参考文档references/cookbook.md2.4 KB
- 参考文档references/known-noise.md1.4 KB
03 SKILL.md 正文
Censys CenQL Reference
When to use
Use this skill whenever the user needs help constructing, debugging, or understanding a Censys Query Language (CenQL) query — field paths, operators, grouping, quoting, or example patterns. This covers requests like:
- "What's the CenQL syntax for matching a port?"
- "How do I write a censys query for SSH hosts not on 22?"
- "What censys fields are available for TLS certificates?"
- "Why is my censys query failing to parse?"
Users sometimes write "CQL." This is a misspelling of CenQL. Answer the question, and use the name CenQL in the reply.
This skill is a reference only — it does not execute queries. Once the query string is built, hand it to censys-search (raw search), censys-aggregate (counts/breakdowns), or censys-view (single-record lookup) to actually run it.
Syntax fundamentals
- Field paths are dot-separated and mirror the JSON document structure:
host.services.port,cert.parsed.subject.common_name. - Operators:
=— exact match (the field value must equal the given term exactly):— contains / flexible match (substring, tokenized, or "in" semantics depending on field type)and,or— boolean combinatorsnot— negation
- Grouping: use parentheses to scope compound expressions, especially when combining
and/oracross nested fields:host.services: (protocol=SSH and port: 22). - CIDR notation: IP range queries use CIDR blocks quoted as strings:
host.ip: '198.51.100.0/24'. - Quoting: wrap any value containing spaces, colons, slashes, or CenQL keywords in single quotes:
cert.parsed.issuer.organization: 'Let''s Encrypt'. - Nested field grouping:
host.services: (...)scopes all conditions inside the parens to the same service entry on the host — critical when a host has multiple services and you don't want conditions matching across unrelated services.
Host fields
- Network:
host.ip,host.services.port,host.services.protocol,host.services.transport_protocol - Banners/headers:
host.services.banner,host.services.banner_hash_sha256,host.services.endpoints.http.headers: (key: "<name>" and value: "<value>")(see Gotchas #3). Note: for HTTP body, title, and favicon content, use the Endpoint fields below —host.services.http.response.bodydoes NOT work in CenQL v2. - TLS/certs:
host.services.tls.certificates.leaf_fp_sha_256,host.services.tls.certificates.leaf_data.* - SSH:
host.services.ssh.server_host_key.fingerprint_sha256 - Fingerprints:
host.services.jarm,host.services.tls.ja3s - Location:
host.location.country,host.location.city,host.location.province,host.location.country_code - Network identity:
host.autonomous_system.asn,host.autonomous_system.name - Classification:
labels(top-level, nothost.labels) - WHOIS:
host.whois.organization.name - Software:
host.services.software.vendor,host.services.software.product,host.services.software.version - OS:
host.operating_system.product,host.operating_system.vendor,host.operating_system.version - Host metadata:
host.service_count(number of services — useful for profiling hosts with a specific service footprint)
Endpoint fields
Certain service-level data lives under host.services.endpoints.<type>.*, NOT
directly under host.services.<type>.*. The endpoints. path component is
required — omitting it returns a 422 "Field not found." This applies to all
endpoint-extracted data: HTTP content, C2 framework configs, and any future
endpoint type Censys adds. When in doubt about a service sub-field, try the
endpoints. path first.
HTTP
| Field | Path |
|---|---|
| Body hash (SHA-256) | host.services.endpoints.http.body_hash_sha256 |
| HTML title | host.services.endpoints.http.html_title |
| Body content (text search) | host.services.endpoints.http.body |
| Favicon hash (SHA-256) | host.services.endpoints.http.favicons.hash_sha256 |
| HTML tags | host.services.endpoints.http.html_tags |
| Response header | host.services.endpoints.http.headers: (key: "<name>" and value: "<value>") |
Cobalt Strike
| Field | Path |
|---|---|
| Watermark | host.services.endpoints.cobalt_strike.x64.watermark |
| Public key | host.services.endpoints.cobalt_strike.x64.public_key |
Both x64 and x86 arch variants exist. These fields only match hosts with
currently active CS listeners — hosts that had CS historically but are now
dark (offline/firewalled) will not appear. Verify the field is indexed by
running a wildcard query (field:*) before interpreting 0 results as "unique."
Certificate fields
- Identity:
cert.names,cert.parsed.subject.common_name,cert.parsed.subject.organization - Issuer:
cert.parsed.issuer.common_name,cert.parsed.issuer.organization - Validity:
cert.parsed.validity_period.not_before,cert.parsed.validity_period.not_after - Fingerprint/trust:
cert.fingerprint_sha256,cert.validation_level
Web property fields
The web property prefix is web.. The prefix webproperty. returns 422 "Field not found".
- Identity:
web.hostname,web.endpoints.ip,web.endpoints.port - Response/classification:
web.endpoints.http.status_code,web.labels - Software:
web.software.vendor,web.software.product. Product values use the Censys name, for examplehttp_serverfor Apache httpd, notApache.
For copy-paste query examples, see ${CLAUDE_SKILL_DIR}/references/cookbook.md.
Query construction patterns
The cookbook gives copy-paste examples. This section teaches how to think about building queries — especially when combining conditions across nested fields.
Compound service matching
Without scoping, conditions on service sub-fields match independently across all services on a host:
# WRONG: matches hosts with RDP on ANY port AND port 7070 running ANY protocol
censys search "host.services.protocol=RDP and host.services.port=7070"
# RIGHT: scopes both conditions to the SAME service entry
censys search 'host.services: (protocol=RDP and port=7070)'
Use separate host.services: (...) blocks to require different services on the same host:
# Hosts with RDP on 3389 AND AnyDesk on 7070 (two distinct services)
censys search 'host.services: (protocol="RDP" and port: 3389) and host.services: (software.product: "AnyDesk" and port: 7070)'
This finds hosts that have both services, but doesn't constrain the total number of services — see host.service_count below.
Service footprint profiling
Combine compound matching with host.service_count to find hosts with a specific service combination and nothing else:
# Hosts running EXACTLY RDP:3389 + AnyDesk:7070, no other services
censys search 'host.services: (protocol="RDP" and port: 3389) and host.services: (software.product: "AnyDesk" and port: 7070) and host.service_count=2'
Purpose-built infrastructure (C2 panels, relay boxes, proxy nodes) tends to have minimal service footprints. Filtering by service_count surfaces these among the noise of multi-service hosts.
Operator choice: = vs :
=— exact match: the field value must equal the term exactly:— flexible match: substring, tokenized, or "in" semantics depending on field type
When it matters: on string fields, : can match substrings (host.services.software.product: nginx matches entries containing "nginx"), while = requires the full value. On enum-like fields (protocol, transport_protocol), both behave the same in practice.
Rule of thumb: use = when you know the exact value you're looking for; use : when exploring or when the value might appear as a substring of a longer string.
CenQL field → JSON output path mapping
CenQL search fields do NOT always match the JSON paths in censys view / censys search output. Use the CenQL column for queries, the jq column for extracting from results:
| Signal | CenQL search field | jq extraction path |
|---|---|---|
| Cert fingerprint | host.services.tls.certificates.leaf_fp_sha_256 |
.services[].tls.fingerprint_sha256 or .services[].cert.fingerprint_sha256 |
| JARM fingerprint | host.services.jarm |
.services[].jarm.fingerprint |
| Software identity | host.services.software.product |
.services[].software[].product |
| HTTP body | host.services.endpoints.http.body (see Gotchas #2) |
.services[].endpoints[].http.body |
| SSH host key | host.services.ssh.server_host_key.fingerprint_sha256 |
.services[].ssh.server_host_key.fingerprint_sha256 (same) |
| Banner hash | host.services.banner_hash_sha256 |
.services[].banner_hash_sha256 (same) |
| Labels | labels (top-level) |
.labels (top-level, NOT host.labels) |
| Body hash | host.services.endpoints.http.body_hash_sha256 |
.services[].endpoints[].http.body_hash_sha256 |
| HTML title | host.services.endpoints.http.html_title |
.services[].endpoints[].http.html_title |
| Response header | host.services.endpoints.http.headers: (key: "Server" and value: "Apache") |
.services[].endpoints[].http.headers.Server.headers[] (object keyed by header name; each value is {"headers": [...]}) |
| Body content | host.services.endpoints.http.body |
.services[].endpoints[].http.body |
| Favicon hash | host.services.endpoints.http.favicons.hash_sha256 |
.services[].endpoints[].http.favicons[].hash_sha256 |
| CS watermark | host.services.endpoints.cobalt_strike.x64.watermark |
.services[].endpoints[].cobalt_strike.x64.watermark |
| CS public key | host.services.endpoints.cobalt_strike.x64.public_key |
.services[].endpoints[].cobalt_strike.x64.public_key |
Escaping rules
- Values containing spaces, colons, slashes, hyphens, or other special characters must be wrapped in single quotes or double quotes:
'value with spaces',"remote-access". Hyphens are especially treacherous —labels: remote-accessfails because the parser reads-accessas negation. - CenQL keywords (
and,or,not) appearing as literal values (not as operators) must be quoted, or the parser will treat them as boolean operators. - Single quotes inside a quoted value are escaped by doubling them in CenQL itself (
'Let''s Encrypt'); when that same string is passed through a shell command line, the shell's own quoting also needs escaping, which produces the doubled pattern'\''seen in cookbook example 6 — one layer for the shell, one for CenQL. - When in doubt, quote the value. Quoting an already-safe token (e.g., a bare number or single word) is harmless; failing to quote a token that needs it causes a parse error or a silently wrong match.
Gotchas
-
host.prefix required in CLI. CenQL v2 via the CLI requireshost.on all host field paths. The Censys web UI does not — queries that work in the browser will fail with a 422 on the CLI. -
endpoints.level for all endpoint-extracted data. HTTP content, Cobalt Strike configs, and other endpoint-level fields live underhost.services.endpoints.<type>.*, NOThost.services.<type>.*. The extraendpoints.nesting is required for every endpoint type. See the Endpoint fields tables above. -
HTTP header queries use a nested key/value block. Put the header name in
keyand the header value invalue, underendpoints.http.headers:host.services: (endpoints.http.headers: (key: "X-Powered-By" and value: "Express")).- A dotted header name does not work.
host.services.endpoints.http.headers.upgradeandhost.services.http.response.headers.serverreturn 422 "Field not found". key=is case-sensitive.key="x-powered-by"matched 29,094 hosts.key="X-Powered-By"matched 1,204,043 hosts. Usekey:to match all casings (1,231,579 hosts).- Put the header block inside the same
host.services: (...)block as the other service conditions. This pins the header to the same service. - For software identity,
host.services.software.productis often simpler. Censys extracts software identity from headers into the software field.
(Verified with the
censysCLI on 2026-10-29.) - A dotted header name does not work.
-
Body text search uses
:, not=. Usehost.services.endpoints.http.body:"search string"(colon, flexible match) for substring/text search within body content. Use=only for exact match on hash fields likebody_hash_sha256. -
software.productvalues are lowercase.software.product="AnyDesk"returns nothing; usesoftware.product: "AnyDesk"(:is case-insensitive) orsoftware.product="anydesk"(exact lowercase).
For known-noise indicators to exclude during triage, see ${CLAUDE_SKILL_DIR}/references/known-noise.md.
Cross-references
- censys-search — execute a constructed CenQL query and return matching raw records.
- censys-aggregate — execute a CenQL query and return counts/breakdowns by field instead of raw records.
- censys-view — single-record lookup by IP/SHA-256/FQDN; does not take a CenQL query.
- censys-censeye — pivot analysis with rarity bounds, useful once a CenQL query surfaces an interesting field value worth exploring further.
- censys-investigate — investigation methodology and multi-step pivoting patterns that build on CenQL queries.
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-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).
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).