Security architecture

Request flow

1. An MCP client connects to the streamable HTTP endpoint, normally over HTTPS on port 9495.
2. The client sends its BigFix REST API token in the Authorization header.
3. The server keeps the authorization value in the request context and validates it against the configured BigFix Server REST API, normally on port 52315.
4. Immediately after successful authentication, the server uses the same bearer token to validate the user's Remediate entitlement against a vendor-defined policy embedded in the signed binary.
5. Only a successful entitlement response authorizes the request; all other responses are returned as a Remediate license denial.
6. The selected MCP tool validates its input.
7. The server contacts only the vendor hosts built into its pin policy.
8. The server formats patch metadata or generates Fixlet content and returns the result to the MCP client.

The server does not create a shared privileged BigFix identity. BigFix authentication remains authoritative for access to the MCP endpoint.

TLS trust directions

Two independent TLS relationships are configured differently:

Embedded vendor certificate pins

The server first performs normal X.509 certificate-chain and hostname validation. It then calculates a SHA3-256 digest over the SPKI of certificates in the verified chain and requires at least one configured pin to match.

Pin updates require a reviewed source change and a newly built and signed server binary. You cannot convert existing hash values into SHA3-256 pins; you must calculate pins from certificate SPKI data.

Authentication and token handling

• Tokens belong in the MCP client's Authorization header, not in config.yaml.
• The server validates the token against the configured BigFix Server.
• The authenticated user must also satisfy the embedded Remediate entitlement policy.
• Raw authorization tokens are not written to logs.
• Audit correlation uses a truncated, process-keyed HMAC-SHA3-256 fingerprint rather than the token value.
• Repeated authentication failures are subject to the configured IP lockout controls.

Tool execution and HITL

The three current tools perform lookup, metadata retrieval, and local content generation. They are registered as read operations and do not execute BigFix write operations. Consequently, the tools do not invoke the server's Human-in-the-Loop approval flow for BigFix writes. Generated content still requires human review before import or deployment.

For Microsoft KB Fixlets, generate_fixlet does not trust client-carried CVE or file metadata. It independently verifies the CVE-to-KB/product/architecture relationship through MSRC and requires every file field to match a fresh Microsoft Update Catalog lookup before rendering. This check fails closed when vendor verification is unavailable. Application generation uses trusted HTTPS source-host enforcement and hash validation; full package provenance binding remains dependent on adding the originating package identifier to that workflow.

Trusted payload hosts

The shipped payload-source allowlist is maintained in config/trusted-download-hosts.json and embedded into each server binary. Startup fails if the policy has an unsupported schema version or contains an empty, malformed, duplicate, non-normalized, or unsorted host list. Only exact lowercase DNS hostnames are accepted; wildcard domains, URLs, ports, and IP literals are prohibited.

FIXLET_TRUSTED_DOWNLOAD_HOSTS is an additive deployment override for publisher hosts that are not appropriate for every release. It cannot remove or replace shipped entries. Editing the embedded policy changes which origins may supply commands' payloads, so additions require the same security review and release rebuild as other bundled trust policy changes.

Logging and audit

The server maintains an operational log at the configured log.file_path and an audit log named mcp_audit.log in the workspace. Protect both logs using operating-system permissions and include them in the organization's retention and incident-response procedures.