DeviceLifecycle-API

Problem

DeviceLifecycle generates valuable operational evidence: the latest CSV inventory, lifecycle outcomes, and execution logs. Internal dashboards, monitoring services, inventory tools, and audit routines may need this data, but giving each consumer direct filesystem access to the automation server would expand the trust boundary unnecessarily.

Exposing lifecycle commands through an API would be even riskier. A reporting integration should not gain authority to quarantine, restore, or delete device identities.

Solution

DeviceLifecycle-API is a separately maintained, read-only HTTP extension. It reads the artifacts already produced by DeviceLifecycle and publishes them through authenticated endpoints.

The relationship is intentionally one-way:

• DeviceLifecycle remains the authoritative producer of reports, logs, state, and administrative decisions;
• DeviceLifecycle-API authenticates consumers and returns existing data;
• consumers format or monitor the responses according to their own requirements.

Stopping or uninstalling the API has no effect on the lifecycle engine. DeviceLifecycle does not depend on the extension to inventory, quarantine, recover, or remove devices.

API contract

The service exposes a small versioned surface under /api/v1:

• /health reports service and source-file availability;
• /metadata returns metadata for the current report and log;
• /report.csv returns the original CSV without transformation;
• /report converts the current CSV to JSON;
• /log?lines=N returns a bounded tail of the latest log;
• /log/file returns the complete latest log.

There are no write endpoints and no client-controlled filesystem paths. The API does not contact Active Directory, Entra ID, Intune, or Microsoft Graph.

Security architecture

The API is designed for internal infrastructure, but it does not assume the internal network is inherently trusted.

Its controls include:

• authentication through the X-API-Key header;
• random 64-character hexadecimal API keys generated during installation;
• constant-time key comparison;
• runtime secrets and configuration stored outside the repository;
• Windows Firewall allowlisting for approved source addresses;
• configurable authentication for the health endpoint;
• disabled Swagger UI, ReDoc, and runtime OpenAPI schema;
• rejection of absolute paths and parent-directory traversal in relative configuration;
• stable file reads that compare size and modification timestamps;
• bounded log-tail requests;
• Cache-Control: no-store and X-Content-Type-Options: nosniff responses;
• rotating request logs that never record the API key.

Plain HTTP is intended only for trusted local or internal segments. Routed or untrusted access should be placed behind an HTTPS reverse proxy.

Installation and operations

A PowerShell installer prepares the complete Windows service environment:

1. validates the DeviceLifecycle report and log sources;
2. validates Python 3.10 or newer;
3. creates the installation and runtime directories;
4. creates a Python virtual environment;
5. installs FastAPI and Uvicorn;
6. generates the API key outside source control;
7. registers a startup Scheduled Task as SYSTEM;
8. creates a restricted firewall rule when approved consumer addresses are configured;
9. starts and validates the service.

The project also provides API-key rotation, configuration validation, update, query examples, and complete uninstallation scripts.

Failure behavior

The service checks that source files are stable before returning them. If a report or log changes while being read, the request fails rather than returning a partially updated artifact.

An unavailable report, malformed CSV, missing log, invalid API key, excessive line request, or unsafe configured path produces an explicit error without modifying the producer’s files.

This keeps the extension observational: it can fail to serve data, but it cannot change the lifecycle state.

Current state

The repository contains the FastAPI application, PowerShell configuration and helper module, installation and startup scripts, validation, API-key rotation, uninstallation, an example consumer, security policy, changelog, API reference, and bilingual architecture documentation.

The public implementation is sanitized. Organization-specific addresses, keys, tenant data, credentials, certificate details, and internal topology remain outside version control.

What it demonstrates

DeviceLifecycle-API demonstrates capability separation in infrastructure tooling. Reporting and monitoring systems receive the minimum interface they need, while privileged device-management authority remains isolated in the main automation. The project combines a deliberately small HTTP contract with authentication, network allowlisting, safe file access, secret isolation, and operational installation tooling.