|
1 | 1 | # Fleet Inventory Parameter Reference |
2 | 2 |
|
3 | | -Read when calling `get_host_details` or `get_cve_systems` to ensure correct parameters. |
| 3 | +Read when calling inventory or vulnerability tools to ensure correct parameters. |
4 | 4 |
|
5 | | -## get_host_details |
| 5 | +## inventory__list_hosts |
6 | 6 |
|
7 | | -**Parameters** (based on user query): |
| 7 | +**Purpose**: List and discover hosts. Use for fleet queries, tag filters, and environment scoping. |
8 | 8 |
|
9 | | -```python |
10 | | -# No filters |
11 | | -get_host_details() |
| 9 | +| Parameter | Type | Required | Example | Notes | |
| 10 | +|-----------|------|----------|---------|-------| |
| 11 | +| `per_page` | integer | No | `10` | **Use 10 on first call.** Not `page_size`. | |
| 12 | +| `page` | integer | No | `1` | Increment for pagination. | |
| 13 | +| `display_name` | string | No | `""` | Filter by display name. Empty string = no filter. | |
| 14 | +| `hostname_or_id` | string | No | `""` | Filter by display_name, fqdn, or id. | |
| 15 | +| `fqdn` | string | No | `""` | Filter by FQDN. | |
| 16 | +| `tags` | string | No | `"ns1/key1=val1"` | Tag filter string (not an array). | |
| 17 | +| `staleness` | string | No | `"fresh"` | One of `fresh`, `stale`, `stale_warning`, `unknown`. | |
| 18 | +| `order_by` | string | No | `"display_name"` | Sort field: `display_name`, `updated`, `created`. | |
| 19 | +| `order_how` | string | No | `"ASC"` | `ASC` or `DESC`. | |
12 | 20 |
|
13 | | -# Specific system |
14 | | -get_host_details(system_id="abc-123") |
| 21 | +**Correct**: |
| 22 | +``` |
| 23 | +inventory__list_hosts(per_page=10, page=1, display_name="") |
| 24 | +inventory__list_hosts(per_page=10, page=1, tags="insights-client/owner=staging") |
| 25 | +``` |
| 26 | + |
| 27 | +**Wrong**: |
| 28 | +``` |
| 29 | +inventory__list_hosts() # Missing per_page guidance; always pass per_page=10 first |
| 30 | +inventory__list_hosts(page_size=100) # Use per_page, not page_size |
| 31 | +inventory__list_hosts(tags=["production"]) # tags is a string, not an array |
| 32 | +``` |
15 | 33 |
|
16 | | -# Hostname pattern |
17 | | -get_host_details(hostname_pattern="web-*") |
| 34 | +**Response envelope**: `{ total, count, page, per_page, results[] }` |
18 | 35 |
|
19 | | -# Tag filter |
20 | | -get_host_details(tags=["production"]) |
| 36 | +**Response fields** (per host in `results[]`): `id`, `display_name`, `fqdn`, `updated`, `last_check_in`, `stale_timestamp`, `per_reporter_staleness`, `groups`, `facts`. Tags when present. No `system_profile` — use `get_host_system_profile` for OS version. |
21 | 37 |
|
22 | | -# RHEL version filter |
23 | | -get_host_details(operating_system__version__startswith="8") |
| 38 | +## inventory__find_host_by_name |
| 39 | + |
| 40 | +**Purpose**: Resolve a hostname or display name to a host record. |
| 41 | + |
| 42 | +| Parameter | Type | Required | Example | |
| 43 | +|-----------|------|----------|---------| |
| 44 | +| `hostname` | string | Yes | `"web-server-01"` | |
24 | 45 |
|
25 | | -# Combined |
26 | | -get_host_details(tags=["production", "web-tier"], operating_system__version__startswith="8") |
| 46 | +``` |
| 47 | +inventory__find_host_by_name(hostname="web-server-01") |
27 | 48 | ``` |
28 | 49 |
|
29 | | -**Response fields**: id, display_name, fqdn, rhel_version, last_seen, tags, stale, satellite_managed |
| 50 | +## inventory__get_host_details |
30 | 51 |
|
31 | | -## get_cve_systems |
| 52 | +**Purpose**: Retrieve full details for **known** host UUIDs. Not for fleet enumeration. |
32 | 53 |
|
33 | | -**Parameters**: `cve_id` (string, format CVE-YYYY-NNNNN, uppercase) |
| 54 | +| Parameter | Type | Required | Example | |
| 55 | +|-----------|------|----------|---------| |
| 56 | +| `host_ids` | string | Yes | `"uuid-1,uuid-2"` | |
34 | 57 |
|
35 | | -```python |
36 | | -get_cve_systems(cve_id="CVE-2024-1234") |
| 58 | +``` |
| 59 | +inventory__get_host_details(host_ids="68ce32aa-57da-49b7-8ded-dc4ad54e520a") |
37 | 60 | ``` |
38 | 61 |
|
39 | | -**Response fields**: cve_id, affected_systems (system_id, display_name, status, remediation_available), total_affected, total_remediated, total_vulnerable |
| 62 | +**Response**: Same envelope as `list_hosts`; host shape is similar (inventory metadata, not guaranteed to include `system_profile`). |
| 63 | + |
| 64 | +**Wrong**: |
| 65 | +``` |
| 66 | +inventory__get_host_details() # host_ids is required |
| 67 | +inventory__get_host_details(system_id="abc-123") # Use host_ids |
| 68 | +inventory__get_host_details(hostname_pattern="web-*") # Not supported; use list_hosts |
| 69 | +inventory__get_host_details(tags=["production"]) # Not supported; use list_hosts |
| 70 | +``` |
| 71 | + |
| 72 | +## inventory__get_host_system_profile |
| 73 | + |
| 74 | +**Purpose**: Retrieve OS version and full system profile for **known** host UUIDs. Use when RHEL version distribution or version-based filtering is required. |
| 75 | + |
| 76 | +| Parameter | Type | Required | Example | Notes | |
| 77 | +|-----------|------|----------|---------|-------| |
| 78 | +| `host_ids` | string | No | `"uuid-1"` or `"uuid-1,uuid-2"` | Comma-separated UUIDs. **One or two at a time** — MCP warns of very large responses. Default `""`. | |
| 79 | + |
| 80 | +``` |
| 81 | +inventory__get_host_system_profile(host_ids="68ce32aa-57da-49b7-8ded-dc4ad54e520a") |
| 82 | +``` |
| 83 | + |
| 84 | +**Response envelope**: `{ total, count, page, per_page, results[] }` (same as `list_hosts`). |
| 85 | + |
| 86 | +**Each `results[]` item** (live shape): `id` + `system_profile` only — not the full inventory record from `list_hosts`. |
| 87 | + |
| 88 | +**`system_profile` fields** (live; OS version equivalents): |
| 89 | +- `operating_system.name` — e.g. `"RHEL"` |
| 90 | +- `operating_system.major` / `operating_system.minor` — e.g. `10` / `1` (no `operating_system.version` string in live responses) |
| 91 | +- `os_release` — e.g. `"10.1"` |
| 92 | +- `installed_packages`, `enabled_services`, `installed_services` |
| 93 | +- Hardware/infrastructure: `cpu_model`, `number_of_cpus`, `system_memory_bytes`, `network_interfaces`, etc. |
| 94 | + |
| 95 | +Use `system_profile.operating_system.version` in docs as the canonical name; at runtime read `major`/`minor`, `os_release`, or `operating_system.name` when `version` is absent. |
| 96 | + |
| 97 | +## vulnerability__get_cve_systems |
| 98 | + |
| 99 | +**Purpose**: List systems affected by a CVE. |
| 100 | + |
| 101 | +| Parameter | Type | Required | Example | Notes | |
| 102 | +|-----------|------|----------|---------|-------| |
| 103 | +| `cve` | string | Yes | `"CVE-2024-1234"` | Required. Not `cve_id`. | |
| 104 | +| `limit` | integer | No | `100` | Records per page (default 10). | |
| 105 | +| `offset` | integer | No | `0` | Pagination offset. | |
| 106 | +| `sort` | string | No | `"-updated"` | Prefix `-` for descending. | |
| 107 | +| `filter_` | string | No | `""` | Full-text filter on system display name. | |
| 108 | +| `system_uuid` | string | No | `"68ce32aa-..."` | Check if a specific system is affected. | |
| 109 | + |
| 110 | +**Correct**: |
| 111 | +``` |
| 112 | +vulnerability__get_cve_systems(cve="CVE-2024-1234", limit=100, offset=0) |
| 113 | +``` |
| 114 | + |
| 115 | +**Wrong**: |
| 116 | +``` |
| 117 | +vulnerability__get_cve_systems(cve_id="CVE-2024-1234") # Use cve, not cve_id |
| 118 | +``` |
| 119 | + |
| 120 | +**Response fields**: affected systems with id, display_name, status, remediation_available; paginate with limit/offset for large result sets. |
40 | 121 |
|
41 | 122 | **Status values**: Vulnerable (patch needed), Patched (no action), Not Affected (exclude) |
42 | 123 |
|
43 | | -## Filtering and Sorting |
| 124 | +## Client-side filtering and sorting |
| 125 | + |
| 126 | +When API filters are insufficient, filter after listing or after fetching profiles: |
44 | 127 |
|
45 | | -**By RHEL**: `[s for s in systems if s['rhel_version'].startswith("8")]` |
46 | | -**By tag**: `[s for s in systems if "production" in s.get('tags', [])]` |
47 | | -**By stale**: `[s for s in systems if not s.get('stale', False)]` |
48 | | -**Sort by last_seen**: `sorted(systems, key=lambda s: s['last_seen'], reverse=True)` |
49 | | -**Sort by display_name**: `sorted(systems, key=lambda s: s['display_name'])` |
| 128 | +**By RHEL major** (requires `get_host_system_profile` data): `[h for h in profiles if h.get('system_profile', {}).get('operating_system', {}).get('major') == 8]` |
| 129 | +**By tag** (when present on host): `[h for h in hosts if any("production" in t for t in h.get('tags', []))]` |
| 130 | +**By stale** (from list_hosts): compare `last_check_in` to `stale_timestamp`, or use `staleness` filter on `list_hosts` |
| 131 | +**Sort by last check-in**: `sorted(hosts, key=lambda h: h.get('last_check_in', ''), reverse=True)` |
| 132 | +**Sort by updated**: `sorted(hosts, key=lambda h: h.get('updated', ''), reverse=True)` |
0 commit comments