Skip to content

REST API Import

Import software inventory from any source using the SentriKat REST API. Use this method for custom integrations, unsupported platforms, or CI/CD pipelines.

Overview

The REST import works by submitting inventory data to the Agent API endpoint. This is the same endpoint that the native Windows and Linux agents use, so imported data is treated identically.

Prerequisites

  • An API key with agent permissions
  • Network access to your SentriKat instance

Quick Start

Submit a software inventory report:

curl -X POST "https://sentrikat.example.com/api/agent/report" \
  -H "X-Agent-Key: sk_agent_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "custom-server-01",
    "os": "FreeBSD 14.0-RELEASE",
    "organization_id": 1,
    "software": [
      {
        "name": "nginx",
        "version": "1.24.0",
        "vendor": "F5, Inc."
      },
      {
        "name": "PostgreSQL",
        "version": "15.4",
        "vendor": "PostgreSQL Global Development Group"
      },
      {
        "name": "OpenSSL",
        "version": "3.1.4",
        "vendor": "OpenSSL Project"
      }
    ]
  }'

Response:

{
  "status": "accepted",
  "asset_id": 42,
  "hostname": "custom-server-01",
  "products_processed": 3,
  "products_matched": 2,
  "vulnerabilities_found": 1
}

Report Schema

Required Fields

Field Type Description
hostname string Unique identifier for the asset
software array List of installed software items

Optional Fields

Field Type Description Default
os string Operating system name and version "Unknown"
organization_id integer Target organization From API key
ip_address string Asset IP address Detected from request
tags array Custom tags for the asset []

Software Item Schema

Field Type Description Required
name string Software product name Yes
version string Installed version Yes
vendor string Software vendor/publisher No
cpe string CPE identifier if known No

CPE Matching

If you provide a cpe field, SentriKat uses it directly for vulnerability matching. Without a CPE, SentriKat performs fuzzy matching on the name and vendor, which may be less accurate.

Use Cases

CI/CD Pipeline Integration

Scan container images or build artifacts and report installed packages:

#!/bin/bash
# Extract packages from Docker image and report to SentriKat

IMAGE="myapp:latest"
SENTRIKAT_URL="https://sentrikat.example.com"
API_KEY="sk_agent_xxxxxxxxxxxx"

# Get package list from container
PACKAGES=$(docker run --rm "$IMAGE" dpkg-query -W -f '{"name":"${Package}","version":"${Version}"},')
PACKAGES="[${PACKAGES%,}]"  # Remove trailing comma, wrap in array

curl -X POST "$SENTRIKAT_URL/api/agent/report" \
  -H "X-Agent-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"hostname\": \"container-$IMAGE\",
    \"os\": \"Docker Container\",
    \"software\": $PACKAGES
  }"

Network Device Inventory

Import software versions from network equipment:

import requests
import json

SENTRIKAT_URL = "https://sentrikat.example.com"
API_KEY = "sk_agent_xxxxxxxxxxxx"

# Example: report firmware versions from network devices
devices = [
    {"hostname": "switch-core-01", "software": [{"name": "Cisco IOS", "version": "17.6.5", "vendor": "Cisco"}]},
    {"hostname": "firewall-01", "software": [{"name": "pfSense", "version": "2.7.2", "vendor": "Netgate"}]},
]

for device in devices:
    response = requests.post(
        f"{SENTRIKAT_URL}/api/agent/report",
        headers={"X-Agent-Key": API_KEY, "Content-Type": "application/json"},
        json=device,
    )
    print(f"{device['hostname']}: {response.json()['status']}")

Scheduled Cron Import

Run periodic imports via cron:

# /etc/cron.d/sentrikat-import
0 2 * * * root /opt/scripts/sentrikat-import.sh >> /var/log/sentrikat-import.log 2>&1

Delta Updates

By default, each report replaces the full inventory for that hostname. To send only changes:

curl -X POST "https://sentrikat.example.com/api/agent/report" \
  -H "X-Agent-Key: sk_agent_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "custom-server-01",
    "delta": true,
    "software_added": [
      {"name": "redis", "version": "7.2.3", "vendor": "Redis Ltd."}
    ],
    "software_removed": [
      {"name": "redis", "version": "7.0.12"}
    ]
  }'

Error Handling

Status Code Meaning Action
200 Success Inventory processed
400 Invalid request body Check JSON schema
401 Invalid API key Verify key in Integrations > Agent Keys
403 Key lacks permissions Ensure key has agent scope
429 Rate limited Wait and retry (see Retry-After header)

Next Steps