mcp-censys-recon

mcp-censys-recon operates as an integrated MCP component, leveraging the Censys Search API to execute instantaneous lookups for host identifiers, network locations, and fully qualified domain names, augmented by the introduction of Model Context Protocol Instructional Sets.

[!CAUTION] This artifact serves purely as a functional demonstration and is explicitly not engineered for production deployment. Official product endorsement or maintenance is not provided.

Conceptual Summary

mcp-censys-recon translates user intent, expressed conversationally, into precise query parameters for Censys, surfacing vital details concerning hosts, DNS records, security certificates, and operational services immediately. It is architected for seamless integration within Claude Desktop or any compatible Model Context Protocol (MCP) client environment.

Developed atop the official Censys Python Software Development Kit, this containerized utility exposes precise threat intelligence mechanisms through Claude-optimized functional interfaces.

[!NEW] Model Context Protocol Instructional Sets

This iteration incorporates Model Context Protocol Instructional Sets—predefined structural guidelines that govern how Claude should process and structure domain intelligence. These sets ensure the delivered reconnaissance findings adhere to consistent, high-fidelity output formats. Further insights on MCP Instructions.

Key Capabilities

• Interactive Querying: Access Censys intelligence using colloquial language.
• Address & Host Resolution: Retrieve DNS mappings, Autonomous System Number (ASN) affiliations, active services, and Transport Layer Security (TLS) context.
• Emergent FQDN Identification: Locate recently cataloged subdomains derived from DNS and certificate data.
• MCP Compliance: Fully operational with standard MCP tool invocation environments.
• MCP Instructional Sets: ✨ Native support for structured guidance templates dictating the analysis and presentation of network intelligence (reference MCP Instructions documentation)
• Containerized Deployment: Utilizes Docker with integrated environment variable support for secure and repeatable execution.
• Efficient API Abstraction: Built upon the streamlined Censys Python SDK.

Available Functions

• resolve_entity_aggregate - Obtain a consolidated summary of IPs, associated DNS names, service banners, and ASN information for a specified domain (aggregates all retrieved data), incorporating native MCP instructions to structure Claude's final presentation.
• resolve_entity_sample - Deliver a limited set (maximum 3) of specific host entries complete with service details, location data, TLS metadata, and total record count metadata, accompanied by structured MCP instructions for deep infrastructure review.
• resolve_network_address - Augment a specific IP address with correlative DNS entries, ASN details, running services, and TLS metadata.
• discover_recent_fqdns - Identify newly recorded Fully Qualified Domain Names for an entity (sourced from DNS logs and certificate transparency logs).
• enumerate_host_services - Rapidly list operational network ports and associated service banners for any given entity identifier (domain or IP).

Operational Initiation Guide

1. Domain Aggregation (resolve_entity_aggregate)

Returns the complete picture by synthesizing all linked IP addresses, DNS aliases, service descriptions, and ASN affiliations pertinent to a given domain identifier. Ideal for holistic infrastructure mapping.

Example:

User: What infrastructure is backing mailchimp.com?

AI: mailchimp.com links to multiple IP ranges managed by The Rocket Science Group (AS2635). The resolution exposes standard ports 80 (HTTP) and 443 (HTTPS), with reverse lookups indicating aliases such as smtp.mailchimp.com and us1.admin.mailchimp.com. Several endpoints consistently return the service signature 'mailchimp-nginx'.

2. Detailed Entity Sampling (resolve_entity_sample)

Provides a representative subset (capped at 3 records) of actual host records matching the domain query, alongside the total quantity of matching records discovered.

Example:

User: Provide granular host details for mailchimp.com

AI: I have identified 42 distinct host records associated with mailchimp.com. Here is a sample set of 3:

IP: 205.201.131.98 - Geolocation: Atlanta, GA (The Rocket Science Group) Active Services: HTTP/Port 80, HTTPS/Port 443, SMTP/Port 25 Operating System Fingerprint: Ubuntu 18.04 IP: 205.201.132.24 - Geolocation: Atlanta, GA (The Rocket Science Group) Active Services: HTTP/Port 80, HTTPS/Port 443 TLS Profile: TLSv1.2, RSA key size 2048-bit IP: 198.2.131.20 - Geolocation: Atlanta, GA (The Rocket Science Group) Active Services: SMTP/Port 25, SMTP/Port 587 TLS Profile: TLSv1.2, Diffie-Hellman exchange 2048-bit 39 additional records remain unlisted in this summary view.

3. Network Address Enrichment (resolve_network_address)

Supplies a complete contextual profile for an IP address, encompassing associated DNS names, ASN, digital certificate data, operational services, and geographical coordinates.

Example:

User: Contextualize the address 184.29.22.16

AI: The address 184.29.22.16 belongs to Akamai's infrastructure (AS20940). It is presenting two active endpoints: HTTP on port 80 and HTTPS on port 443. Hosting location is within the United States, and it utilizes a security certificate signed by Let's Encrypt.

4. Recent FQDN Tracking (discover_recent_fqdns)

Locates newly observed Fully Qualified Domain Names affiliated with an entity, cross-referencing both dynamic DNS updates and certificate issuance logs.

Example:

User: Which new hostnames has microsoft.com registered in the preceding 72 hours? AI: Over the last 3 days, 17 unique FQDNs were detected for microsoft.com, including:

login.microsoft.com (observed in both DNS and Certificates) api.microsoft.com (observed exclusively in Certificate logs) graph.microsoft.com (observed exclusively in DNS logs) teams.microsoft.com (observed in both DNS and Certificates)

5. Port Status Enumeration (enumerate_host_services)

Provides a rapid report detailing active network ports and the identity of the software responding on those endpoints for a given address.

Examples:

User: Which ports are open on example.com?

AI: The entity example.com (IP: 93.184.216.34) reports the following active services:

Service: HTTP on TCP Port 80 (Last known activity: 2 hours prior) Service: HTTPS on TCP Port 443 (Last known activity: 2 hours prior)

Deployment Procedure

bash

Retrieve source code

git clone https://github.com/yourusername/mcp-censys-recon.git cd mcp-censys-recon

Build the container image

docker build -t mcp/censys-recon .

The '.env' file must contain the following credentials:

CENSYS_API_ID=your_censys_api_id CENSYS_API_SECRET=your_censys_api_secret

MCP Integration Configuration

Insert this configuration block into your Claude Desktop environment settings:

"censys_recon": { "command": "docker", "args": [ "run", "--rm", "-i", "--env-file", "/Users/yourname/.env.censys_recon", "mcp/censys-recon" ] }

Visual Demonstration

mcp-censys-recon operational sequence within Claude Desktop, invoking resolve_entity_aggregate, resolve_entity_sample, and resolve_network_address functions:

This illustration depicts an entity aggregation query on mailchimp.com, returning associated IP structures, ASN affiliation, subdomain inventory, service banners, and infrastructural context — all initiated from a single natural language request.

This visualization showcases a granular entity sampling request for mailchimp.com, yielding IP addresses, ASN, hostname lists, BGP data, TLS specifications, service reports, and infrastructure layout.

This example demonstrates a network address enrichment query on 23.204.1.14, providing resolved coordinates, forward/reverse DNS mappings, and service inventories.

Issue Resolution

No Information Returned:

• Confirm the target asset is publicly discoverable via Censys scans.
• Verify the validity of your API credentials and check current rate limit consumption.
• DNS-derived outputs are contingent upon the freshness of Censys indexing.

Speed Optimization Notes:

• For faster throughput, constrain queries to one domain or IP identifier at a time.
• Rely on resolve_entity_aggregate or resolve_network_address for targeted data retrieval.

API Response Formatting Problems:

• Ensure you are utilizing the most recent software version if formatting errors persist.
• Pagination is managed internally: resolve_entity_aggregate collects all available data, whereas resolve_entity_sample returns a controlled preview.
• Queries involving entities with vast result sets may require extended processing duration due to iterative API calls.

Constraints

• discover_recent_fqdns provides 'last observed' timestamps, not necessarily the true 'first seen' time of the FQDN.
• This utility is optimized for sequential, single-target conversational analysis (batch scanning is unsupported).
• resolve_entity_sample is capped at three records to maintain output verbosity at a manageable level, even if more data exists.

Licensing

MIT License

Credits

• Censys Python SDK (https://github.com/censys/censys-python)
• Model Context Protocol Specification (https://modelcontextprotocol.io/)
• Claude Desktop Environment (https://www.anthropic.com)