<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# Asset Inventory Management — API Reference

## AWS EC2 Asset Discovery

```python
import boto3

session = boto3.Session(profile_name="security-audit")
ec2 = session.client("ec2")

# List all instances across regions
paginator = ec2.get_paginator("describe_instances")
for page in paginator.paginate():
    for reservation in page["Reservations"]:
        for instance in reservation["Instances"]:
            print(instance["InstanceId"], instance.get("PrivateIpAddress"))
```

## ServiceNow CMDB Sync

```python
import requests

SNOW_URL = "https://corp.service-now.com/api/now/table/cmdb_ci_server"
HEADERS = {"Authorization": "Bearer <token>", "Accept": "application/json"}

# Query all servers
resp = requests.get(SNOW_URL, headers=HEADERS, params={"sysparm_limit": 500})

# Create CI record
requests.post(SNOW_URL, headers=HEADERS, json={
    "name": "web-prod-01",
    "ip_address": "10.0.1.10",
    "os": "Linux",
    "classification": "Production",
})
```

## runZero Asset Export

```python
RUNZERO_URL = "https://console.runzero.com/api/v1.0"
HEADERS = {"Authorization": "Bearer <export-token>"}

# Export all assets
resp = requests.get(f"{RUNZERO_URL}/org/assets", headers=HEADERS, params={
    "search": "alive:t AND type:server",
    "fields": "id,addresses,os,hw,names",
})
```

## Asset Data Contract

```python
@dataclass
class Asset:
    """
    Fields:
        asset_id: Unique identifier (cloud instance ID, serial, MAC)
        hostname: FQDN or short hostname
        ip_addresses: All known IPs (v4 and v6)
        os: Operating system identifier
        asset_type: ec2 | endpoint | container | network_device
        criticality: critical | high | standard | low
        source: Discovery source (aws, edr, nmap, cmdb)
        last_seen: ISO 8601 timestamp of last observation
    """
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Discovery and reconciliation completed |
| 1 | Drift detected — review required |
| 2 | Discovery source unreachable |
