### Install Dependencies with Poetry for Development

Source: https://github.com/censys/censys-python/blob/main/README.md

Installs project dependencies using poetry after cloning the repository. This is part of the development setup process for the Censys Python library.

```sh
git clone git@github.com:censys/censys-python.git
cd censys-python/
poetry install
```

--------------------------------

### Manage Host Assets with Censys ASM (Python)

Source: https://context7.com/censys/censys-python/llms.txt

Illustrates how to query and manage host assets using the `HostsAssets` class from `censys.asm`. Examples include retrieving all host assets, filtering by tags, getting a specific asset by IP, adding and retrieving comments, and adding or deleting tags.

```python
from censys.asm import HostsAssets

hosts = HostsAssets()

# Get all host assets (paginated)
for asset in hosts.get_assets(page_number=1):
    print(asset)

# Get assets filtered by tag
for asset in hosts.get_assets(tag=["production"], tag_operator="is"):
    print(asset)

# Get a specific asset by IP
asset = hosts.get_asset_by_id("192.168.1.1")
print(asset)

# Add a comment to an asset
result = hosts.add_comment("192.168.1.1", "Reviewed and approved")
print(result)

# Get comments on an asset
for comment in hosts.get_comments("192.168.1.1"):
    print(comment)

# Add a tag to an asset
result = hosts.add_tag("192.168.1.1", "critical", color="#FF0000")
print(result)

# Delete a tag from an asset
result = hosts.delete_tag("192.168.1.1", "old-tag")
print(result)
```

--------------------------------

### Import Censys SearchClient (Python)

Source: https://github.com/censys/censys-python/blob/main/examples/README.md

Demonstrates how to import the SearchClient and specific index clients (Hosts, Certificates) from the censys.search package.

```python
from censys.search import SearchClient

# Access only the hosts index
from censys.search import CensysHosts

# Access only the certificates index
from censys.search import CensysCerts
```

--------------------------------

### Install Censys Python Library with Poetry

Source: https://github.com/censys/censys-python/blob/main/README.md

Installs the Censys Python library using poetry after cloning the repository. This method is useful for development or when managing dependencies with poetry.

```sh
git clone https://github.com/censys/censys-python.git
cd censys-python/
poetry install
```

--------------------------------

### Manage Seeds with Censys ASM (Python)

Source: https://context7.com/censys/censys-python/llms.txt

Provides examples for managing seeds (IP addresses, domains, CIDRs, ASNs) using the `Seeds` class from `censys.asm`. This includes retrieving all seeds, filtering by type or label, getting specific seeds by ID, adding new seeds, replacing seeds by label, and deleting seeds by label or ID.

```python
from censys.asm import Seeds

s = Seeds()

# Get all seeds
seeds = s.get_seeds()
print(seeds)

# Get seeds filtered by type
seeds = s.get_seeds(seed_type="IP_ADDRESS")
seeds = s.get_seeds(seed_type="DOMAIN_NAME")

# Get seeds filtered by label
seeds = s.get_seeds(label="production")

# Get a specific seed by ID
seed = s.get_seed_by_id(12345)
print(seed)

# Add seeds
new_seeds = [
    {"type": "IP_ADDRESS", "value": "192.168.1.1", "label": "webserver"},
    {"type": "DOMAIN_NAME", "value": "example.com", "label": "main-domain"},
    {"type": "CIDR", "value": "10.0.0.0/24", "label": "internal"},
    {"type": "ASN", "value": "AS12345", "label": "our-asn"},
]
result = s.add_seeds(new_seeds)
print(result)

# Replace seeds by label
updated_seeds = [
    {"type": "IP_ADDRESS", "value": "192.168.1.2", "label": "webserver"},
]
result = s.replace_seeds_by_label("webserver", updated_seeds)
print(result)

# Delete seeds by label
result = s.delete_seeds_by_label("old-label")
print(result)

# Delete a specific seed by ID
result = s.delete_seed_by_id(12345)
print(result)
```

--------------------------------

### Get Cloud Asset Counts with Censys Python

Source: https://context7.com/censys/censys-python/llms.txt

Shows how to retrieve counts of assets discovered across different cloud providers using the Censys Python library. Examples include host, domain, object store, and subdomain counts, as well as known vs. unknown host counts, all filterable by date.

```python
from censys.asm import Clouds
from datetime import date

clouds = Clouds()

# Get host counts by cloud provider (since a specific date)
host_counts = clouds.get_host_counts(since=date(2023, 1, 1))
print(host_counts)

# Get domain counts by cloud
domain_counts = clouds.get_domain_counts(since=date(2023, 1, 1))
print(domain_counts)

# Get object store counts by cloud
object_store_counts = clouds.get_object_store_counts(since=date(2023, 1, 1))
print(object_store_counts)

# Get subdomain counts by cloud
subdomain_counts = clouds.get_subdomain_counts(since=date(2023, 1, 1))
print(subdomain_counts)

# Get known vs unknown host counts
unknown_counts = clouds.get_unknown_counts()
print(unknown_counts)
```

--------------------------------

### Import Censys AsmClient (Python)

Source: https://github.com/censys/censys-python/blob/main/examples/README.md

Shows how to import the AsmClient from the censys.asm package for interacting with Censys ASM services.

```python
from censys.asm import AsmClient
```

--------------------------------

### Track Events with Censys ASM Logbook (Python)

Source: https://context7.com/censys/censys-python/llms.txt

Demonstrates how to use the `Logbook` class from `censys.asm` to track changes and events across the attack surface. This includes getting a cursor to read events, optionally starting from a specific date or filtering by event types, and processing events to potentially enrich with additional host data.

```python
from censys.asm import Logbook, HostsAssets
import datetime

logbook = Logbook()
hosts = HostsAssets()

# Get a cursor to start reading events
cursor = logbook.get_cursor()

# Get a cursor starting from a specific date
cursor = logbook.get_cursor(start=datetime.datetime(2023, 1, 1))

# Get a cursor with filters for specific event types
cursor = logbook.get_cursor(filters=["HOST_RISK", "HOST_PORT"])

# Available filters:
# CERT, CERT_RISK, DOMAIN, DOMAIN_EXPIRATION_DATE, DOMAIN_MAIL_EXCHANGE_SERVER,
# DOMAIN_NAME_SERVER, DOMAIN_REGISTRAR, DOMAIN_RISK, DOMAIN_SUBDOMAIN, HOST,
# HOST_CERT, HOST_PORT, HOST_PROTOCOL, HOST_RISK, HOST_SOFTWARE, HOST_VULNERABILITY

# Get events from cursor
for event in logbook.get_events(cursor):
    if event["operation"] == "ADD":
        print(event)
        # Enrich with additional host data
        if "ipAddress" in event.get("entity", {}):
            host = hosts.get_asset_by_id(event["entity"]["ipAddress"])
            print(host)
```

--------------------------------

### Manage Tags for Hosts and Certificates

Source: https://context7.com/censys/censys-python/llms.txt

Enables creation, management, and assignment of tags to organize hosts and certificates. Supports listing, creating, getting, updating, and deleting tags, as well as applying them to documents. Requires the `censys.search` library.

```python
from censys.search import CensysHosts, CensysCerts

h = CensysHosts()
c = CensysCerts()

# List all tags
tags = h.list_all_tags()
print(tags)

# Create a new tag
tag = c.create_tag("test-tag")
print(tag)

# Create a tag with a custom color
tag = c.create_tag("important-tag", color="#FF0000")
print(tag)

# Get a tag by ID
tag = h.get_tag("123")
print(tag)

# Update a tag
tag = c.update_tag("123", "updated-tag-name", color="#00FF00")
print(tag)

# Delete a tag
h.delete_tag("123")

# List tags on a document
tags = c.list_tags_on_document(
    "fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426"
)
print(tags)

# Add a tag to a document
h.add_tag_to_document("1.1.1.1", "tag_id")

# Remove a tag from a document
c.remove_tag_from_document(
    "fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426",
    "tag_id"
)
```

--------------------------------

### Get Risk Instances with Censys ASM Python SDK

Source: https://github.com/censys/censys-python/blob/main/docs/usage-asm.rst

Illustrates how to retrieve risk-related information using the Risks class. Examples include fetching all risk events, all risk instances, a specific risk instance by ID, all risk types, and a specific risk type by ID.

```python
from censys.asm import Risks

r = Risks()

# Get risk events
risk_events = r.get_risk_events()
print(risk_events)

# Get a dict that returns all risk instances
risk_instances = r.get_risk_instances()
print(risk_instances)

# Get a single risk instance by ID
risk_instance = r.get_risk_instance(1)
print(risk_instance)

# Get risk types
risk_types = r.get_risk_types()
print(risk_types)

# Get a single risk type by ID
risk_type = r.get_risk_type("missing-common-security-headers")
print(risk_type)
```

--------------------------------

### Install Censys Python Library

Source: https://github.com/censys/censys-python/blob/main/README.md

Installs the Censys Python library using pip. This is the primary method for adding the library to your Python environment. It ensures you have the latest stable version.

```sh
pip install censys
```

--------------------------------

### View Host Events

Source: https://context7.com/censys/censys-python/llms.txt

Get a timeline of events (changes) for a specific host within a time range.

```APIDOC
## GET /api/v2/hosts/{ip}/events

### Description
Get a timeline of events (changes) for a specific host within a time range.

### Method
GET

### Endpoint
/api/v2/hosts/{ip}/events

### Parameters
#### Path Parameters
- **ip** (string) - Required - The IP address of the host.

#### Query Parameters
- **per_page** (integer) - Optional - The number of events to return per page.
- **start_time** (string or date) - Optional - The start of the time range for events. Can be an ISO 8601 formatted string or a `datetime.date` object.
- **end_time** (string or date) - Optional - The end of the time range for events. Can be an ISO 8601 formatted string or a `datetime.date` object.

### Request Body
(Not applicable)

### Request Example
```python
from censys.search import CensysHosts
from datetime import date

h = CensysHosts()

# Fetch a list of events for the specified IP address
events = h.view_host_events("1.1.1.1")
print(events)

# Filter events by date range
events = h.view_host_events(
    "1.1.1.1",
    per_page=1,
    start_time=date(2022, 1, 1),
    end_time=date(2022, 1, 31)
)
print(events)
# {
#     'ip': '1.1.1.1',
#     'events': [
#         {
#             'timestamp': '2022-01-01T00:00:01.713Z',
#             'service_observed': {...},
#             '_event': 'service_observed'
#         }
#     ],
# }
```

### Response
#### Success Response (200)
- **ip** (string) - The IP address of the host.
- **events** (array) - A list of event objects associated with the host.

#### Response Example
```json
{
  "ip": "1.1.1.1",
  "events": [
    {
      "timestamp": "2022-01-01T00:00:01.713Z",
      "service_observed": {
        "port": 80,
        "transport_protocol": "tcp"
      },
      "_event": "service_observed"
    }
  ]
}
```
```

--------------------------------

### Get Hosts by Certificate using Censys Python v2

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Demonstrates how to fetch a list of hosts associated with a specific certificate SHA256 fingerprint using the `get_hosts_by_cert` method. Requires initializing CensysCerts.

```python
from censys.search import CensysCerts

c = CensysCerts()

# Example certificate SHA256 fingerprint
cert_sha256 = "fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426"

hosts, links = c.get_hosts_by_cert(cert_sha256)
print(hosts)
```

--------------------------------

### Manage Security Risks with Censys ASM (Python)

Source: https://context7.com/censys/censys-python/llms.txt

Provides examples for querying and managing security risks using the `Risks` class from `censys.asm`. This covers retrieving risk events, risk instances (with or without events), searching risk instances, patching risk instances (e.g., to acknowledge or remediate), and retrieving risk types.

```python
from censys.asm import Risks

risks = Risks()

# Get risk events
events = risks.get_risk_events(
    start="2023-01-01T00:00:00Z",
    end="2023-12-31T23:59:59Z",
    limit=100,
)
print(events)

# Get all risk instances
instances = risks.get_risk_instances(include_events=True)
print(instances)

# Get a specific risk instance
instance = risks.get_risk_instance(12345, include_events=True)
print(instance)

# Search risk instances
results = risks.search_risk_instances({
    "query": "severity:critical",
    "pageSize": 50,
})
print(results)

# Patch a risk instance (e.g., acknowledge or remediate)
result = risks.patch_risk_instance(12345, {
    "status": "ACKNOWLEDGED",
    "comment": "Under review by security team",
})
print(result)

# Get risk types
types = risks.get_risk_types(limit=50, include_events=True)
print(types)

# Get a specific risk type
risk_type = risks.get_risk_type("exposed-database")
print(risk_type)
```

--------------------------------

### Get Tag

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Retrieves details for a specific tag.

```APIDOC
## GET /api/v2/tags/{tag_id}

### Description
Retrieves details for a specific tag.

### Method
GET

### Endpoint
/api/v2/tags/{tag_id}

### Parameters
#### Path Parameters
- **tag_id** (string) - Required - The unique identifier of the tag to retrieve.

### Request Example
None

### Response
#### Success Response (200)
- **tag_id** (string) - The unique identifier for the tag.
- **name** (string) - The name of the tag.
- **color** (string) - The color associated with the tag.

#### Response Example
```json
{
  "tag_id": "123",
  "name": "Example Tag",
  "color": "#FFA500"
}
```
```

--------------------------------

### Search Assets with Censys ASM Python SDK

Source: https://github.com/censys/censys-python/blob/main/docs/usage-asm.rst

Shows how to search for assets and perform aggregations using the InventorySearch class. Examples include searching with specific workspaces and queries, and aggregating results by a given field.

```python
from censys.asm import InventorySearch

i = InventorySearch()

# Get a dict that contains a list of hits for a search query with pagination
assets = i.search(workspaces=["my_workspace"], query="host.services.http.response.body: /.*test.*/")
print(assets)

# Aggregate search results by a field
aggregation = i.aggregate(workspaces=["my_workspace"], query="host.location.country_code: 'US'", aggregation={"term": {"field": "host.autonomous_system.bgp_prefix", "numberOfBuckets": 50}})
print(aggregation)

# Get list of all available fields
fields = i.fields()
print(fields)
```

--------------------------------

### Get Hosts by Certificate API (Certs Only)

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Fetches a list of hosts associated with a specific certificate SHA256 hash.

```APIDOC
## GET /certificates/{sha256}/hosts

### Description
Fetches a list of hosts associated with a specific certificate SHA256 hash. This method is only available for the CensysCerts index.

### Method
GET

### Endpoint
/certificates/{sha256}/hosts

### Parameters
#### Path Parameters
- **sha256** (string) - Required - The SHA256 hash of the certificate.

### Response
#### Success Response (200)
- **hosts** (array) - A list of hosts associated with the certificate.
- **links** (object) - Pagination links.

#### Response Example
```json
{
  "hosts": [
    {
      "ip": "1.1.1.1"
    }
  ],
  "links": {
    "next": "/v2/certificates/fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426/hosts?page_token=next_token"
  }
}
```
```

--------------------------------

### Get Comments for Certificate using Censys Python v2

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Shows how to fetch a list of comments for a specific certificate using the `get_comments` method. Requires initializing CensysCerts.

```python
from censys.search import CensysCerts

c = CensysCerts()

# Example certificate SHA256 fingerprint
cert_sha256 = "fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426"

comments = c.get_comments(cert_sha256)
print(comments)
```

--------------------------------

### Manage Subdomain Asset Tags with Censys ASM Python SDK

Source: https://github.com/censys/censys-python/blob/main/docs/usage-asm.rst

Shows how to add tags to subdomain assets within a given domain using the AsmClient. This example focuses on tagging a specific subdomain.

```python
from censys.asm import AsmClient

client = AsmClient()

sub = client.get_subdomains("my_domain.com")

# Add a tag to a subdomain under my_domain.com
sub.add_tag("sub.my_domain.com", "New")
```

--------------------------------

### Get Host Metadata with CensysHosts

Source: https://context7.com/censys/censys-python/llms.txt

Retrieves metadata about the Hosts index, including dataset information, using the CensysHosts client. Requires the `censys.search` library.

```python
from censys.search import CensysHosts

h = CensysHosts()

metadata = h.metadata()
print(metadata)
```

--------------------------------

### Get Host Metadata using Censys Python v2

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Shows how to retrieve metadata for Censys Hosts using the `metadata_hosts` method. This functionality is exclusive to the CensysHosts index and requires initializing CensysHosts.

```python
from censys.search import CensysHosts

h = CensysHosts()

# Example Host ID
host_id = "1.1.1.1"

host_metadata = h.metadata_hosts(host_id)
print(host_metadata)
```

--------------------------------

### View Assets on Censys ASM Platform (Python)

Source: https://github.com/censys/censys-python/blob/main/docs/usage-asm.rst

Demonstrates how to view assets on the Censys ASM platform using the `censys.asm.HostsAssets` client. It shows how to get a generator for hosts and retrieve a single host by its ID. Requires the `censys` library.

```python
from censys.asm import HostsAssets

h = HostsAssets()

# Get a generator that returns hosts
hosts = h.get_assets()
print(next(hosts))

# Get a single host by ID (here we get host with ID="0.0.0.0")
host = h.get_asset_by_id("0.0.0.0")
print(host)
```

--------------------------------

### Create Logbook Cursor with Censys ASM Python SDK

Source: https://github.com/censys/censys-python/blob/main/docs/usage-asm.rst

Provides examples of creating logbook cursors for retrieving filtered events using the Logbook class. It demonstrates creating cursors based on timestamps, event IDs, and event type filters, including combinations.

```python
from censys.asm import Logbook

l = Logbook()

# Get a logbook cursor beginning at timestamp "2020-04-22T06:55:01.000Z"
cursor = l.get_cursor("2020-04-22T06:55:01.000Z")
print(cursor)

# Get a logbook cursor beginning at event ID=10
cursor = l.get_cursor(10)
print(cursor)

# Get a logbook cursor that filters on events of type "CERT" and "CERT_RISK"
cursor = l.get_cursor(filters=["CERT", "CERT_RISK"])
print(cursor)

# Get a logbook cursor combining previous start ID and filters
cursor = l.get_cursor(10, filters=["CERT", "CERT_RISK"])
print(cursor)
```

--------------------------------

### Add Seeds to Censys ASM Platform (Python)

Source: https://github.com/censys/censys-python/blob/main/docs/usage-asm.rst

Provides examples for adding seeds to the Censys ASM platform using the `censys.asm.Seeds` client. It covers adding a list of seeds and replacing existing seeds with a specified label. Requires the `censys` library.

```python3
from censys.asm import Seeds

s = Seeds()

# Add a list of seeds. To add a single seed, just pass a list containing one seed.
# Here, we add two ASN seeds.
seed_list = [
    {"type": "ASN", "value": 99998, "label": "seed-test-label"},
    {"type": "ASN", "value": 99999, "label": "seed-test-label"},
]
s.add_seeds(seed_list)

# Add a list of seeds, replacing existing seeds with a specified label
# Here, all seeds with label="seed-test-label" will be removed and then
# Seeds 99996 and 99997 will be added.
seed_list = [{"type": "ASN", "value": 99996}, {"type": "ASN", "value": 99997}]
s.replace_seeds_by_label("seed-test-label", seed_list)
```

--------------------------------

### Initialize ASM Client and Access APIs (Python)

Source: https://context7.com/censys/censys-python/llms.txt

Shows how to initialize the `AsmClient` from the `censys.asm` library and access various ASM API modules like seeds, hosts, certificates, domains, logbook, clouds, risks, and inventory. This client serves as a unified entry point for all ASM functionalities.

```python
from censys.asm import AsmClient

client = AsmClient()

# Access various ASM APIs
seeds = client.seeds
hosts = client.hosts
certificates = client.certificates
domains = client.domains
subdomains = client.subdomains
logbook = client.logbook
clouds = client.clouds
risks = client.risks
inventory = client.inventory
```

--------------------------------

### Configure Censys API Credentials via CLI

Source: https://context7.com/censys/censys-python/llms.txt

Provides instructions on setting up Censys API credentials using the command-line interface. It covers configuring both the Search API and the ASM API separately, including prompts for API keys/secrets and user preferences like color output. It also shows how to set credentials using environment variables.

```bash
# Configure Search API credentials
censys config
# Censys API ID: YOUR_API_ID
# Censys API Secret: YOUR_API_SECRET
# Do you want color output? [y/n]: y
# Successfully authenticated for your@email.com

# Configure ASM API credentials
censys asm config
# Censys ASM API Key: YOUR_ASM_API_KEY
# Do you want color output? [y/n]: y
# Successfully authenticated

# Or use environment variables
export CENSYS_API_ID="your-api-id"
export CENSYS_API_SECRET="your-api-secret"
export CENSYS_ASM_API_KEY="your-asm-api-key"
```

--------------------------------

### Execute Inventory Search (Bash)

Source: https://github.com/censys/censys-python/blob/main/docs/usage-cli.rst

Executes an inventory search query using the Censys ASM CLI.

```bash
censys asm search
```

--------------------------------

### List Seeds (Bash)

Source: https://github.com/censys/censys-python/blob/main/docs/usage-cli.rst

Lists seeds from Censys ASM, with options to filter by type and/or label, and to output in CSV format. The output can be redirected to a file.

```bash
censys asm list-seeds --csv >> seeds.csv
```

```bash
censys asm list-seeds -t 'IP_ADDRESS' -l 'Some Label' >> filtered_seeds.json
```

--------------------------------

### Managing Tags

Source: https://context7.com/censys/censys-python/llms.txt

Create, manage, and assign tags to organize hosts and certificates.

```APIDOC
## Managing Tags

### Description
Create, manage, and assign tags to organize hosts and certificates.

### Method
GET, POST, PUT, DELETE

### Endpoint
`/api/v2/tags` (and similar for hosts/certificates, specific endpoints not provided in text)

### Parameters
#### Path Parameters (Get/Update/Delete Tag)
- **tag_id** (string) - Required - The ID of the tag.

#### Path Parameters (List Tags on Document)
- **document_id** (string) - Required - The ID of the host or certificate.

#### Query Parameters (Add/Remove Tag from Document)
- **tag_id** (string) - Required - The ID of the tag to add or remove.

#### Request Body (Create/Update Tag)
- **name** (string) - Required - The name of the tag.
- **color** (string) - Optional - The color of the tag (e.g., "#FF0000").

### Request Example
```python
from censys.search import CensysHosts, CensysCerts

h = CensysHosts()
c = CensysCerts()

# List all tags
tags = h.list_all_tags()
print(tags)

# Create a new tag
tag = c.create_tag("test-tag")
print(tag)

# Create a tag with a custom color
tag = c.create_tag("important-tag", color="#FF0000")
print(tag)

# Get a tag by ID
tag = h.get_tag("123")
print(tag)

# Update a tag
tag = c.update_tag("123", "updated-tag-name", color="#00FF00")
print(tag)

# Delete a tag
h.delete_tag("123")

# List tags on a document
tags = c.list_tags_on_document(
    "fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426"
)
print(tags)

# Add a tag to a document
h.add_tag_to_document("1.1.1.1", "tag_id")

# Remove a tag from a document
c.remove_tag_from_document(
    "fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426",
    "tag_id"
)
```

### Response
#### Success Response (200)
- **tags** (list of objects) - A list of tag objects.
- **tag** (object) - The created, retrieved, or updated tag object.

#### Response Example
```json
{
  "tags": [
    {
      "id": "123",
      "name": "test-tag",
      "color": null
    }
  ]
}
```
```

--------------------------------

### Perform Inventory Searches with Censys Python

Source: https://context7.com/censys/censys-python/llms.txt

Illustrates various ways to search inventory using the Censys Python library. This includes basic searches, paginated results, retrieving all results, searching with specific fields, and performing aggregations. It also shows how to list available fields.

```python
from censys.asm import InventorySearch

inventory = InventorySearch()

# Basic search
results = inventory.search(query="host.services.service_name: HTTP")
print(results)

# Search with pagination
results = inventory.search(
    query="host.services.port: 443",
    page_size=50,
    pages=3,  # Get 3 pages of results
)
print(results["hits"])

# Get all results (use pages=-1)
results = inventory.search(
    query="host.services.port: 22",
    page_size=100,
    pages=-1,  # Returns all available pages
)
print(len(results["hits"]))

# Search with specific fields
results = inventory.search(
    query="host.services.service_name: HTTPS",
    fields=["host.ip", "host.services.port"],
    sort=["host.ip"],
)
print(results)

# Aggregate inventory data
aggregation = inventory.aggregate(
    workspaces=["workspace-id"],
    query="host.services.service_name: HTTP",
    aggregation={
        "field": "host.services.port",
        "num_buckets": 10,
    },
)
print(aggregation)

# List available fields
fields = inventory.fields()
print(fields)
```

--------------------------------

### Get Comments API (Certs Only)

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Fetches a list of comments for a specific certificate.

```APIDOC
## GET /certificates/{sha256}/comments

### Description
Fetches a list of comments for a specific certificate. This method is only available for the CensysCerts index.

### Method
GET

### Endpoint
/certificates/{sha256}/comments

### Parameters
#### Path Parameters
- **sha256** (string) - Required - The SHA256 hash of the certificate.

### Response
#### Success Response (200)
- **comments** (array) - A list of comments associated with the certificate.

#### Response Example
```json
[
  {
    "commentid": 1,
    "created_at": "2023-01-01T12:00:00Z",
    "comment": "This is a test comment."
  }
]
```
```

--------------------------------

### Get Saved Query by ID (Bash)

Source: https://github.com/censys/censys-python/blob/main/docs/usage-cli.rst

Retrieves a specific saved query from Censys ASM using its unique ID.

```bash
censys asm get-saved-query-by-id --query-id 'Some ID'
```

--------------------------------

### List All Tags

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Fetches a list of all available tags.

```APIDOC
## GET /api/v2/tags

### Description
Fetches a list of all available tags.

### Method
GET

### Endpoint
/api/v2/tags

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **tags** (array) - A list of tag objects.
  - **tag_id** (string) - The unique identifier for the tag.
  - **name** (string) - The name of the tag.
  - **color** (string) - The color associated with the tag (e.g., "#FF0000").

#### Response Example
```json
{
  "tags": [
    {
      "tag_id": "tag123",
      "name": "Important Hosts",
      "color": "#FF0000"
    },
    {
      "tag_id": "tag456",
      "name": "Vulnerable Systems",
      "color": "#00FF00"
    }
  ]
}
```
```

--------------------------------

### List Hosts and Certificates with Tags (Python)

Source: https://context7.com/censys/censys-python/llms.txt

Demonstrates how to list hosts and certificates associated with a specific tag using the Censys Python library. This functionality is useful for filtering and retrieving specific assets based on predefined tags.

```python
from censys import censys_python

h = censys_python.hosts.CensysHostsClient()
c = censys_python.certificates.CensysCertificatesClient()

# List hosts/certs with a specific tag
hosts = h.list_hosts_with_tag("123")
certs = c.list_certs_with_tag("123")
```

--------------------------------

### Bulk View Certificates with CensysCerts

Source: https://context7.com/censys/censys-python/llms.txt

Retrieves information for multiple certificates simultaneously by providing a list of their SHA-256 fingerprints. Requires the `censys.search` library.

```python
from censys.search import CensysCerts

c = CensysCerts()

certificates = c.bulk_view([
    "82689890be745aef821ee4a988a0b81331f714d7301b288976fab36219b1f493",
    "9b00121b4e85d50667ded1a8aa39855771bdb67ceca6f18726b49374b41f0041",
])
for certificate in certificates:
    print(certificate["fingerprint_sha256"])
```

--------------------------------

### Get Tag (Python)

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Fetches a specific tag by its ID from the Censys Hosts index. Requires an initialized CensysHosts object and a valid tag ID.

```python
from censys.search import CensysHosts

h = CensysHosts()

# Fetch a tag.
tag = h.get_tag("123")
print(tag)
```

--------------------------------

### View Host Differences using Censys Python v2

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Illustrates how to view differences for a specific host using the `view_host_diff` method. This is only available for the CensysHosts index and requires initializing CensysHosts.

```python
from censys.search import CensysHosts

h = CensysHosts()

# Example Host ID
host_id = "1.1.1.1"

host_diff = h.view_host_diff(host_id)
print(host_diff)
```

--------------------------------

### CensysCerts - Bulk View Certificates

Source: https://context7.com/censys/censys-python/llms.txt

Retrieve details for multiple certificates simultaneously using their SHA-256 fingerprints.

```APIDOC
## Bulk View Certificates

### Description
Look up multiple certificates at once by their SHA-256 fingerprints.

### Method
POST

### Endpoint
`/api/v2/certificates/bulk` (or similar, specific endpoint not provided in text)

### Parameters
#### Request Body
- **fingerprints** (list of strings) - Required - A list of SHA-256 fingerprints for the certificates.

### Request Example
```python
from censys.search import CensysCerts

c = CensysCerts()

certificates = c.bulk_view([
    "82689890be745aef821ee4a988a0b81331f714d7301b288976fab36219b1f493",
    "9b00121b4e85d50667ded1a8aa39855771bdb67ceca6f18726b49374b41f0041",
])
for certificate in certificates:
    print(certificate["fingerprint_sha256"])
```

### Response
#### Success Response (200)
- **certificates** (list of objects) - A list of certificate objects corresponding to the provided fingerprints.

#### Response Example
```json
[
  {
    "fingerprint_sha256": "82689890be745aef821ee4a988a0b81331f714d7301b288976fab36219b1f493"
  },
  {
    "fingerprint_sha256": "9b00121b4e85d50667ded1a8aa39855771bdb67ceca6f18726b49374b41f0041"
  }
]
```
```

--------------------------------

### Bulk View Hosts

Source: https://context7.com/censys/censys-python/llms.txt

Look up multiple hosts at once using concurrent requests for efficient bulk operations.

```APIDOC
## POST /api/v2/hosts/bulk

### Description
Look up multiple hosts at once using concurrent requests for efficient bulk operations.

### Method
POST

### Endpoint
/api/v2/hosts/bulk

### Parameters
#### Request Body
- **ips** (array of strings) - Required - A list of IP addresses to retrieve information for.

### Request Example
```python
from censys.search import CensysHosts

h = CensysHosts()

IPS = ["1.1.1.1", "1.1.1.2", "1.1.1.3"]

hosts = h.bulk_view(IPS)
print(hosts)
# {
#     '1.1.1.1': {'ip': '1.1.1.1', 'services': [...], ...},
#     '1.1.1.2': {'ip': '1.1.1.2', 'services': [...], ...},
#     '1.1.1.3': {'ip': '1.1.1.3', 'services': [...], ...},
# }
```

### Response
#### Success Response (200)
- **{ip_address}** (object) - An object where keys are IP addresses and values are the host data for each IP.

#### Response Example
```json
{
  "1.1.1.1": {
    "ip": "1.1.1.1",
    "services": [
      {
        "port": 80,
        "service_name": "HTTP"
      }
    ]
  },
  "1.1.1.2": {
    "ip": "1.1.1.2",
    "services": [
      {
        "port": 443,
        "service_name": "HTTPS"
      }
    ]
  }
}
```
```

--------------------------------

### Manage Saved Queries with Censys ASM Python SDK

Source: https://github.com/censys/censys-python/blob/main/docs/usage-asm.rst

Provides an example of initializing the SavedQueries class from the censys.asm library, intended for managing saved queries within the Censys ASM platform.

```python
from censys.asm import SavedQueries

s = SavedQueries()
```

--------------------------------

### Get Logbook Events with Censys ASM Python SDK

Source: https://github.com/censys/censys-python/blob/main/docs/usage-asm.rst

Demonstrates how to retrieve logbook events using the Logbook class. It shows fetching all events and retrieving events based on a previously created cursor.

```python
from censys.asm import Logbook

l = Logbook()

# Get a generator that returns all events
events = l.get_events()
print(next(events))

# Get events based off cursor specifications
events = l.get_events(cursor)
print(next(events))
```

--------------------------------

### View Host Differences with CensysHosts

Source: https://context7.com/censys/censys-python/llms.txt

Compares a host's state between two points in time or compares two different hosts using the CensysHosts client. Requires the `censys.search` library.

```python
from censys.search import CensysHosts
from datetime import date

h = CensysHosts()

# Compare a host at two different times
diff = h.view_host_diff(
    "1.1.1.1",
    at_time=date(2022, 1, 1),
    at_time_b=date(2022, 6, 1)
)
print(diff)

# Compare two different hosts
diff = h.view_host_diff("1.1.1.1", ip_b="8.8.8.8")
print(diff)
```

--------------------------------

### View Host

Source: https://context7.com/censys/censys-python/llms.txt

Fetch detailed information about a specific host by IP address, including services, location, and autonomous system data.

```APIDOC
## GET /api/v2/hosts/{ip}

### Description
Fetch detailed information about a specific host by IP address, including services, location, and autonomous system data.

### Method
GET

### Endpoint
/api/v2/hosts/{ip}

### Parameters
#### Path Parameters
- **ip** (string) - Required - The IP address of the host to retrieve.

#### Query Parameters
- **at_time** (string or date) - Optional - The timestamp to retrieve host data for. Can be an ISO 8601 formatted string or a `datetime.date` object.

### Request Body
(Not applicable)

### Request Example
```python
from censys.search import CensysHosts
from datetime import date

h = CensysHosts()

# Fetch a specific host and its services
host = h.view("8.8.8.8")
print(host)
# {
#     'ip': '8.8.8.8',
#     'services': [{'port': 53, 'service_name': 'DNS', ...}],
#     'location': {'country': 'United States', 'country_code': 'US', ...},
#     'autonomous_system': {'asn': 15169, 'description': 'GOOGLE', ...},
#     ...
# }

# Fetch host at a specific point in time (requires historical API access)
host = h.view("8.8.8.8", at_time="2021-03-01T17:49:05Z")

# Using datetime object
host = h.view("8.8.8.8", at_time=date(2021, 3, 1))
```

### Response
#### Success Response (200)
- **ip** (string) - The IP address of the host.
- **services** (array) - A list of services observed on the host.
- **location** (object) - Geographic location information for the host.
- **autonomous_system** (object) - Information about the host's autonomous system.

#### Response Example
```json
{
  "ip": "8.8.8.8",
  "services": [
    {
      "port": 53,
      "service_name": "DNS"
    }
  ],
  "location": {
    "country": "United States",
    "country_code": "US"
  },
  "autonomous_system": {
    "asn": 15169,
    "description": "GOOGLE"
  }
}
```
```

--------------------------------

### Initialize and Use AsmClient (Python)

Source: https://github.com/censys/censys-python/blob/main/docs/usage-asm.rst

Shows how to initialize the Censys AsmClient and use it to interact with Seeds, Assets, and Events APIs. The AsmClient provides a unified interface for these Censys services.

```python
from censys.asm import AsmClient

client = AsmClient()

# Get all seeds
seeds = client.seeds.get_seeds()
print(seeds)

# Get all domain assets
domains = client.domains.get_assets()
print(next(domains))

# Get all logbook events
logbook_events = client.logbook.get_events()
print(next(logbook_events))
```

--------------------------------

### Search Hosts using Censys Python v2

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Demonstrates how to perform searches against the Censys Hosts index using the `censys.search.v2.api.CensysSearchAPIv2.search` method. This requires initializing the CensysHosts class.

```python
from censys.search import CensysHosts

h = CensysHosts()

# Example search query
query = "ip: 1.1.1.1"

hosts, links = h.search(query)
print(hosts)
```

--------------------------------

### Aggregate Host Data using Censys Python v2

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Demonstrates how to aggregate data from the Hosts index to view resources as a spectrum based on attributes, using the `censys.search.v2.api.CensysSearchAPIv2.aggregate` method. Requires initializing CensysHosts.

```python
from censys.search import CensysHosts

h = CensysHosts()

# Example aggregation query
query = "services.service_name: http"
aggregation = h.aggregate(query)
print(aggregation)
```

--------------------------------

### Create Tag

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Creates a new tag. Optionally, a color can be specified for the tag.

```APIDOC
## POST /api/v2/tags

### Description
Creates a new tag. Optionally, a color can be specified for the tag.

### Method
POST

### Endpoint
/api/v2/tags

### Parameters
#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name for the new tag.
- **color** (string) - Optional - The color for the tag, in hexadecimal format (e.g., "#00FF00").

### Request Example
```json
{
  "name": "test-tag",
  "color": "#00FF00"
}
```

### Response
#### Success Response (201)
- **tag_id** (string) - The unique identifier for the newly created tag.
- **name** (string) - The name of the tag.
- **color** (string) - The color associated with the tag.

#### Response Example
```json
{
  "tag_id": "newtag789",
  "name": "test-tag",
  "color": "#00FF00"
}
```
```

--------------------------------

### Manage Censys Saved Queries (Python)

Source: https://github.com/censys/censys-python/blob/main/docs/usage-asm.rst

Demonstrates how to perform CRUD operations on Censys saved queries using the Python client. This includes getting all queries, retrieving a single query by ID, adding a new query, updating an existing query, and deleting a query.

```python
from censys import censys_python

s = censys_python.CensysPython()

# Get a dict that contains a list of saved queries
saved_queries = s.get_saved_queries()
print(saved_queries)

# Get a single saved query by ID
saved_query = s.get_saved_query_by_id("query_id")
print(saved_query)

# Add a saved query
saved_query = s.add_saved_query("my_saved_query", "host.services.http.response.body: /.*test.*/")
print(saved_query)

# Update a saved query
saved_query = s.edit_saved_query_by_id("query_id", "my_updated_saved_query", "host.services.http.response.body: /.*test.*/")
print(saved_query)

# Delete a saved query
s.delete_saved_query_by_id("query_id")
```

--------------------------------

### List Saved Queries (Bash)

Source: https://github.com/censys/censys-python/blob/main/docs/usage-cli.rst

Lists saved queries from Censys ASM, with options to filter by query name prefix and/or filter term. The output can be in CSV format and redirected to a file.

```bash
censys asm list-saved-queries --csv >> saved_queries.csv
```

```bash
censys asm list-saved-queries --query-name-prefix 'Some Prefix' --filter-term 'Some Term' >> filtered_saved_queries.json
```

--------------------------------

### Bulk View Hosts using Censys Python v2

Source: https://github.com/censys/censys-python/blob/main/docs/usage-v2.rst

Illustrates how to fetch data for multiple Hosts in a single request using the `censys.search.v2.api.CensysSearchAPIv2.bulk_view` method. This requires initializing the CensysHosts class.

```python
from censys.search import CensysHosts

h = CensysHosts()

# List of Host IDs
host_ids = ["1.1.1.1", "8.8.8.8"]

hosts_data = h.bulk_view(host_ids)
print(hosts_data)
```

--------------------------------

### Execute Saved Query by Name (Bash)

Source: https://github.com/censys/censys-python/blob/main/docs/usage-cli.rst

Executes a saved query in Censys ASM using its name.

```bash
censys asm execute-saved-query-by-name --query-name 'Some query name'
```