AGENT SKILL

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

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 combinators
    • not — negation
  • Grouping: use parentheses to scope compound expressions, especially when combining and/or across 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.body does 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, not host.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 example http_server for Apache httpd, not Apache.

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-access fails because the parser reads -access as 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

  1. host. prefix required in CLI. CenQL v2 via the CLI requires host. 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.

  2. endpoints. level for all endpoint-extracted data. HTTP content, Cobalt Strike configs, and other endpoint-level fields live under host.services.endpoints.<type>.*, NOT host.services.<type>.*. The extra endpoints. nesting is required for every endpoint type. See the Endpoint fields tables above.

  3. HTTP header queries use a nested key/value block. Put the header name in key and the header value in value, under endpoints.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.upgrade and host.services.http.response.headers.server return 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. Use key: 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.product is often simpler. Censys extracts software identity from headers into the software field.

    (Verified with the censys CLI on 2026-10-29.)

  4. Body text search uses :, not =. Use host.services.endpoints.http.body:"search string" (colon, flexible match) for substring/text search within body content. Use = only for exact match on hash fields like body_hash_sha256.

  5. software.product values are lowercase. software.product="AnyDesk" returns nothing; use software.product: "AnyDesk" (: is case-insensitive) or software.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
censys/censys-ai-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).

★ 14
censys
censys/censys-ai-skills

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).

★ 14
censys
censys/censys-ai-skills

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).

★ 14
censys
censys/censys-ai-skills

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.

★ 14
censys
censys/censys-ai-skills

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).

★ 14
censys
censys/censys-ai-skills

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).

★ 14