AI Skills

censys-ai-skills is a public, Censys-owned repo that contains skills, hooks, helper scripts, tests, and more that leverage the cencli Platform CLI tool. These skills can be added to Claude Code and other AI tools. The skills add the ability to look up assets, run searches, create aggregations, execute pivot analysis jobs, and more.

The censys-ai-skills GitHub repo always contains the most up-to-date information about how to install and use the skills. This document contains general instructions for setup.

Prerequisites

• Install and configure cencli prior to installing censys-ai-skills.
  • censys-ai-skills requires version 1.0 or newer of cencli.
• To use censys-censeye or retrieve certificate history, your organization must have access to the Adversary Investigation module.

Installation

Installation instructions for Claude Code and other tools are provided below. The skills are standalone markdown files that work with any AI coding assistant that supports custom instructions. The Claude Code plugin system handles skill loading and path resolution automatically. Other tools require manual setup.

claude plugin marketplace add censys/censys-ai-skills
claude plugin install censys

git clone https://github.com/censys/censys-ai-skills.git

# Example: include in an AGENTS.md or system prompt
@censys-ai-skills/skills/censys-search/SKILL.md
@censys-ai-skills/skills/censys-cenql/SKILL.md

Notes for non-Claude Code harnesses

• Path variables: Skills reference files using ${CLAUDE_SKILL_DIR} and ${CLAUDE_PLUGIN_ROOT}. These are Claude Code-specific. On other harnesses, resolve them relative to the skill folder and repo root respectively. The model can typically infer the correct paths from context.
• Scripts: The scripts/ directory contains shell helpers censys-count.sh, censys-export.sh, censys-to-sqlite.sh). These work on any harness with bash access. Reference them by their path relative to the repo root.
• Hooks: The hooks/ directory provides advisory warnings for Claude Code's hook system. Other harnesses can ignore this directory.
• Skill content: The methodology, CenQL syntax, CLI flags, and operational caveats in each skill are plain markdown. They work as reference material regardless of the harness.

Skills included in the repo

The following skills and tools are included in the censys-ai-skills repo.

Skills reference each other via cross-reference sections. A methodology skill like censys-investigate will call out to censys-search for pivot queries, censys-timeline for historical analysis, and censys-cenql for field path lookups. The command wrappers are self-contained and can be used independently for one-off tasks.

Censys Credit costs

Each skill wraps one or more cencli subcommands. Most cencli commands will deduct at least one credit from your balance. More credits are consumed if pagination is involved. The censys-investigate tool can invoke 10 to 50 or more calls depending on input. Reference the documentation in GitHub for more information on credit estimates and how to limit credit expenditure.

How to use Censys AI skills

Censys AI skills are particularly helpful in the following use-cases:

• You want to provide complex prompts in plain language and receive human-readable and actionable output.
  • The censys-investigate skill runs through a baseline collection phase and then branches into decision trees based on findings.
    • Manually pivot and review indicators before running the investigate skill to save on credits.
  • Aggregate before you paginate. You can use censys-aggregate to see the shape of data before you investigate deeper.
• You want to look up hosts in bulk and save on credit costs.
  • Instruct your agent to use censys-enrich to lookup hosts in bulk without deducting from your credit balance.
• Your prompt needs more than one call, more than one data source, or needs to run again at a later date.
  • You can instruct your agent to save output of an investigation or prompt locally and then diff a week later to evaluate changes over time.
• You want to search programmatically with built-in guardrails.
  • The censys-search skill is limited to 100 results by default. You can override this with the --max-pages flag.
  • Instruct your agent with clear call limits when needed.
• You want to save the results of your searches, lookups, and investigations locally.
  • Every pull is saved. A follow-up question about the same data can use jq instead of a Censys API call.

Example prompts

Use the following prompts with your agent. Replace placeholder values with values that apply to your use-case.

Enrich and highlight IPs for SOC triage

These prompts assume you receive an indicator list from a SIEM, TI feed, or a phishing report. ips.txt is one IP per line.

Prompt 1

enrich every IP in ips.txt, save the raw output to enrich.json, and give me a table sorted by reputation score with label, country, hosting information, VPN/Tor flags, and open ports

• This prompt will use the enrichment API and save on credit costs for this bulk lookup.

Prompt 2

pull the full host records for the hosts with both RDP and SMB open and tell me what's actually running, which OS, and whether anything looks like a known C2 or scanner

• Each full host lookup will cost one credit.

Prompt 3

write a bash script called triage.sh that enriches every IP in ips.txt, writes enrich.json and a ranked table, and prints just the IPs with a MALICIOUS label and RDP or SMB open

Weekly exposure diff for a vulnerability team

aggregate hosts in [IPrange] by port, then by software, and tell me what stands out. pull the same ranges into perimeter_[date].db and diff against last week: new hosts, new ports, removed hosts

• The credit cost for this prompt is approximately three credits for a range under 100 hosts and one credit per additional page.
• The diff needs a baseline. Run the pull once to create the first perimeter_[date].db, then run it again the following week and point the diff at the earlier file.

Censys ARC Rapid Response advisory blast radius for a SOC team

what CenQL would find hosts running [product] [version]? validate the field names before running anything. aggregate by country and ASN, then restrict to our ASNs and pull the list, cap at 3 pages

• Cost for this prompt may vary from two to six credits or more.

Third-party or merger check

aggregate everything Censys sees for [acquired-co.com] by port and software, and list anything that looks like admin or database exposure. turn this into a one-page summary for the review doc

• Cost for this prompt may vary from two to four credits or more.

Pivot from a confirmed hit for threat hunting

run censeye on [IP] and show pivot candidates with rarity counts, rarest first. if justified, investigate [discovered-IPs] fully, cap total calls at 30, write findings to findings.md

• This prompt may cost 30 credits or more.