Itential Golden Config

Golden Configurations - Developer Skills Guide

Golden Configurations define the "desired state" for device configurations. They enable compliance checking, grading, and remediation of configuration drift across your network.

Customization

Before using this skill, check custom/org/, custom/team/, and custom/dev/ in this skill's own directory. Read every .md file found, in that order (any folder may be empty or absent). Apply them in addition to everything below — where a file overrides a specific rule from this document, prefer the override; more specific wins (dev over team over org). See .claude/CUSTOMIZATION.md for the full framework and what belongs in which layer.

Gotchas

• NEVER wire a remediation task — see ## Remediation below for the full prohibited-task list and the correct config-push pattern. This skill detects, reports, and grades compliance; it does not remediate, no exceptions.
• deviceType must match exactly: "cisco-ios" not "Cisco IOS" or "ios"
• variables in PUT /configuration_manager/node/config must be a JSON object, not a string
• updateVariables boolean is REQUIRED in node config update — omitting it silently skips variable merge
• Compliance run is async — returns batchId, not the report. Poll with GET /compliance_reports/batch/{batchId}
• Plan instance results are inside groups[].plans[], not top-level
• nodeId in compliance plan is the configId, NOT the node name — get it from the tree version response
• Node path uses node name separated by / — root varies by tree (e.g., base, Global)
• Parser name must match the device's ostype or compliance parsing produces wrong results
• Parser template must reference an existing parser — list with GET /configurations/parser
• Parser lexRules are validated with safe-regex — unsafe patterns (catastrophic backtracking) are rejected
• Config spec regex patterns need escaped backslashes in JSON ("\\d+" not "\d+")
• Duplicate tree names blocked — "A tree with the name already exists"
• Node path leading / is auto-stripped — /base/DataCenter and base/DataCenter are equivalent
• Creating a new tree version requires a base parameter specifying which version to clone from

What is Golden Config?

Golden Config provides a hierarchical, version-controlled system for defining what device configurations should look like:

• Trees - Top-level containers associated with a device type (e.g., cisco-ios, arista-eos)
• Versions - Each tree can have multiple versions (e.g., initial) to evolve standards over time
• Nodes - Hierarchical structure within a version (e.g., Global → EMEA → London). Child nodes inherit from parents.
• Config Specs - Rules attached to each node that define required, disallowed, or informational configuration lines
• Variables - Tree-level variables accessible by all node templates via Jinja2 {{ var }} syntax
• Configuration Parsers - Define how raw CLI config is tokenized for comparison against config specs
• Compliance Reports - Results of checking device configs against golden config specs
• Grading - Scoring formula that produces a grade (Pass/Review/Fail) from compliance results
• Remediation - out of scope; see ## Remediation section.

How Inheritance Works

Global (base node)
  ├── config spec: service password-encryption, aaa new-model, ntp server
  │
  ├── DataCenter
  │     ├── config spec: ip http secure-server, ip ssh version 2
  │     │
  │     └── Atlanta
  │           ├── devices: [IOS-CAT8KV-1]
  │           └── config spec: (empty or site-specific rules)
  │
  └── Branch
        └── ...

A device assigned to Atlanta is checked against all inherited specs: Global + DataCenter + Atlanta. This allows global standards at the top with site-specific overrides at the leaves.

API Reference

Base Path: /configuration_manager

Trees

Create a golden config tree:

POST /configuration_manager/configs

{
  "name": "Cisco IOS Baseline",
  "deviceType": "cisco-ios"
}

Response creates the tree with version initial, a root node, and an empty config spec:

{
  "id": "699b70325ae7d527cda5fff0",
  "name": "Cisco IOS Baseline",
  "version": "initial",
  "deviceType": "cisco-ios",
  "root": {
    "name": "base",
    "attributes": {
      "devices": [],
      "deviceGroups": [],
      "remediationWorkflow": null,
      "configId": "699b70325ae7d527cda5ffef"
    },
    "children": []
  },
  "variables": {}
}

Device types: cisco-ios, cisco-ios-xr, cisco-nx, arista-eos, json (for non-CLI structured data like AWS Security Groups)

variables are NOT set on create — the create body only accepts name, deviceType, and description. Variables are set after creation via PUT /configuration_manager/node/config on the base node with updateVariables: true:

{
  "treeId": "{treeId}",
  "treeVersion": "initial",
  "nodePath": "base",
  "data": { "template": "", "variables": { "hostname": "router.example.com" } },
  "updateVariables": true
}

Bulk delete trees — DELETE /configuration_manager/configs requires body {"treeIds": ["id1", "id2"]}. A tree cannot be deleted while it is referenced by a compliance plan — delete the plan first.

Nodes

Create a child node:

POST /configuration_manager/configs/{treeId}/initial/base

{
  "name": "DataCenter"
}

Response includes the auto-created config spec:

{
  "name": "DataCenter",
  "attributes": {
    "devices": [],
    "deviceGroups": [],
    "remediationWorkflow": null,
    "configId": "699b705b5ae7d527cda5fff2"
  },
  "children": []
}

Add devices to a node:

POST /configuration_manager/configs/{treeId}/initial/base/DataCenter/Atlanta/devices

{
  "devices": ["IOS-CAT8KV-1"]
}

Node path format: Node paths use the node name separated by /. Root varies by tree (e.g., Global, base). Example: Global/EMEA/London, base/DataCenter/Atlanta.

Node Configuration (Template)

This is where you define the golden config rules for a node. You write config as a template string, and the platform parses it into structured config spec lines.

PUT /configuration_manager/node/config

{
  "treeId": "699b70325ae7d527cda5fff0",
  "treeVersion": "initial",
  "nodePath": "base",
  "data": {
    "template": "service password-encryption\naaa new-model\n<e/>ntp server {{ ntp_server }}\n<i/>version {/ {{ version_regex }} /}\n{d/}ip domain-lookup",
    "variables": {
      "ntp_server": "ntp1.east.itential.com",
      "version_regex": "\\d+\\.\\d+"
    }
  },
  "updateVariables": true
}

• template - config text using golden config template syntax (see below)
• variables - JSON object (NOT a string) with variable values for {{ var }} substitutions
• updateVariables - required boolean - whether to merge variables into the tree-level variables

Response: {"status": "success", "message": "Node Config updated"}

The platform automatically parses the template text into structured lines in the config spec.

Golden Config Template Syntax

The template uses special prefixes to control how each line is evaluated during compliance checks.

Line Prefixes

Control evalMode and severity for each line:

Variable and Pattern Syntax

Regex as Variable

You can store regex patterns in tree variables and reference them in the template. This is useful when the same pattern is reused or needs to be configurable:

version {/ {{ version_regex }} /}
ip access-list extended ACL-VLAN100-IN
 10 permit tcp 10.100.1.0 0.0.0.255 any eq www
 {/ {{ acl_line_regex }} /} permit tcp 10.100.1.0 0.0.0.255 any eq 443
 30 deny ip any any log

With variables:

{
  "version_regex": "\\d+\\.\\d+",
  "acl_line_regex": "^(10000|[1-9][0-9]{0,3})"
}

Template Examples

Global baseline (mixed evalModes):

<i/>version {/\d+\.\d+/}
service password-encryption
{i/}hostname {/\S+/}
aaa new-model
aaa authentication login default local
<e/>ntp server {{ ntp_server }}
{d/}service internal
{d/}<e/>ip domain-lookup

Interface blocks with nested children:

<e/>interface GigabitEthernet1.1
 description reserved for dev1
<e/>interface GigabitEthernet1.2
 description reserved for dev2

Child lines (indented) inherit the parent's evalMode. The interface line is required+error, its child description line is also checked.

Jinja2 loops for dynamic interface generation:

{% for interface in interfaces %}
{i/}interface {{ interface['name'] }}
  {i/}description {{ interface['description']|upper }}
  {i/}ip address {{ interface['ip'] }} {{ interface['mask'] }}
  {i/}no shutdown
{% endfor %}

This generates lines for each entry in the interfaces array variable. Jinja2 filters like |upper are supported.

Disallowed with regex:

{d/}<e/>access-list 4 permit 14.126.166.15
{i/}<e/>access-list 5 permit {/192\.168\.1/}

Config Specs

Config specs are the parsed representation of the template. When you update a node's template, the platform auto-parses it into a config spec with structured lines. You can also create/update config specs directly.

Config spec structure:

{
  "id": "699b70325ae7d527cda5ffef",
  "deviceType": "cisco-ios",
  "template": "service password-encryption\naaa new-model\n<e/>ntp server {{ ntp_server }}",
  "lines": [
    {
      "id": "699b6f14c9ed5903",
      "words": [
        { "type": "literal", "value": "service" },
        { "type": "literal", "value": "password-encryption" }
      ],
      "lines": [],
      "evalMode": "required",
      "fixMode": "manual",
      "severity": "warning",
      "ordering": "none",
      "membership": "default"
    },
    {
      "id": "699b6f14dec62d74",
      "words": [
        { "type": "literal", "value": "ntp" },
        { "type": "literal", "value": "server" },
        { "type": "literal", "value": "ntp1.east.itential.com" }
      ],
      "lines": [],
      "evalMode": "required",
      "fixMode": "manual",
      "severity": "error",
      "ordering": "none",
      "membership": "default"
    }
  ]
}

Word types:

• literal - exact match (e.g., service, password-encryption)
• variable - matches any value, captures it
• regex - matches a regex pattern (from {/pattern/} or {/ {{ var }} /})

Config spec fields:

• evalMode - required, disallowed, ignored
• fixMode - manual or automatic
• severity - error, warning, info
• ordering - none or strict
• membership - default
• lines - nested child lines (for hierarchical configs like interface blocks)

JSON Specs (for json device type):

Configuration Parsers

Parsers define how raw CLI configuration text is tokenized into words and lines for comparison against config specs. Different OS types need different parsing rules.

Config parser structure:

{
  "id": "67c5c272cd98641b4bae74ad",
  "name": "a10-acos",
  "template": "cisco-ios",
  "lexRules": [
    ["(\\r\\n|\\r|\\n)", "end_line"],
    ["$", "end_line"],
    ["\"(?:[^\\\\\"\\r\\n]|\\\\.)*\"", "word"],
    ["\\S+", "word"]
  ]
}

• name - Parser name (typically matches the OS type)
• template - Base parser template to inherit rules from (e.g., 'cisco-ios'). List available parsers with GET /configuration_manager/configurations/parser.
• lexRules - Array of [regex_pattern, token_type] pairs. Token types: end_line, word, comment. Patterns are validated with safe-regex — unsafe patterns are rejected.

Compliance Plans

Compliance plans group golden config nodes with their target devices into a runnable plan. Running a plan triggers compliance checks for all nodes and produces a batch of reports.

Create a compliance plan:

POST /configuration_manager/compliance_plans

{
  "name": "IOS Baseline Compliance",
  "options": {
    "description": "Checks all Cisco IOS devices against the baseline golden config",
    "nodes": [
      {
        "treeId": "699b70325ae7d527cda5fff0",
        "version": "initial",
        "nodeId": "699b705b5ae7d527cda5fff3",
        "devices": ["IOS-CAT8KV-1"],
        "deviceGroups": [],
        "variables": {}
      }
    ]
  }
}

Node fields (all required):

• treeId - the golden config tree ID
• version - tree version (e.g., "initial")
• nodeId - the configId of the node (NOT the node name)
• devices - array of device names to check
• deviceGroups - array of device group IDs (use [] if none)
• variables - variable overrides for this node (use {} if none)

Response:

{
  "_id": "699b8c3b5ae7d527cda5fff6",
  "name": "IOS Baseline Compliance",
  "description": "Checks all Cisco IOS devices against the baseline golden config",
  "throttle": 5,
  "nodes": [
    {
      "treeId": "699b70325ae7d527cda5fff0",
      "version": "initial",
      "nodeId": "699b705b5ae7d527cda5fff3",
      "variables": {},
      "devices": ["IOS-CAT8KV-1"],
      "deviceGroups": []
    }
  ]
}

Run a compliance plan:

POST /configuration_manager/compliance_plans/run

{
  "planId": "699b8c3b5ae7d527cda5fff6",
  "options": {}
}

Response:

{
  "message": "Successfully started compliance plan.",
  "planId": "699b8c3b5ae7d527cda5fff6",
  "instanceId": "699b8c4a5ae7d527cda5fff7"
}

Get plan run instance (shows status, processed devices, batch ID):

POST /configuration_manager/search/compliance_plan_instances

{
  "searchParams": {
    "instanceId": "699b8c4a5ae7d527cda5fff7"
  }
}

Response (plans are inside groups[], not top-level):

{
  "totalCount": 1,
  "groups": [
    {
      "totalCount": 1,
      "plans": [
        {
          "id": "699b8c4a5ae7d527cda5fff7",
          "name": "IOS Baseline Compliance",
          "jobStatus": "complete",
          "planId": "699b8c3b5ae7d527cda5fff6",
          "batchId": "699b8c4a5ae7d527cda5fff8",
          "started": "2026-02-22T23:07:54.697Z",
          "finished": "2026-02-22T23:07:59.735Z",
          "nodes": [
            {
              "treeId": "699b70325ae7d527cda5fff0",
              "nodeId": "699b705b5ae7d527cda5fff3",
              "status": "completed",
              "devices": ["IOS-CAT8KV-1"],
              "processedDevices": ["IOS-CAT8KV-1"]
            }
          ]
        }
      ]
    }
  ]
}

Use the batchId to retrieve compliance reports via GET /configuration_manager/compliance_reports/batch/{batchId}.

Add nodes to an existing plan:

POST /configuration_manager/compliance_plans/nodes

{
  "planId": "699b8c3b5ae7d527cda5fff6",
  "nodes": [
    {
      "treeId": "699b70325ae7d527cda5fff0",
      "version": "initial",
      "nodeId": "699b705b5ae7d527cda5fff2",
      "devices": ["IOS-CAT8KV-2"],
      "deviceGroups": [],
      "variables": {}
    }
  ]
}

Compliance Reports

Results of compliance checks showing what passed, what failed, and what needs remediation.

Run compliance:

POST /configuration_manager/compliance_reports

{
  "options": {
    "treeId": "699b70325ae7d527cda5fff0",
    "version": "initial",
    "nodePath": "base/DataCenter/Atlanta",
    "devices": ["IOS-CAT8KV-1"]
  }
}

Response (async - compliance runs in background):

{
  "status": 202,
  "message": "compliance batch 699b70d55ae7d527cda5fff4 started",
  "batchId": "699b70d55ae7d527cda5fff4"
}

Run compliance against a raw config string (without fetching from device):

POST /configuration_manager/compliance_reports/config

{
  "options": {
    "treeId": "699b70325ae7d527cda5fff0",
    "version": "initial",
    "nodePath": "base/DataCenter/Atlanta",
    "deviceName": "IOS-CAT8KV-1",
    "configuration": "service password-encryption\naaa new-model\n..."
  }
}

Useful for testing compliance against a config you already have (e.g., from a backup or generated config) without connecting to the device.

Get batch results (returns array of report summaries):

GET /configuration_manager/compliance_reports/batch/{batchId}

Each entry has id (report ID), batchId, treeId, nodePath, deviceName, specId, inheritedSpecIds.

Get detailed report:

GET /configuration_manager/compliance_reports/details/{reportId}

{
  "id": "699b70d95ae7d527cda5fff5",
  "deviceName": "IOS-CAT8KV-1",
  "nodePath": "base/DataCenter/Atlanta",
  "timestamp": "2026-02-22T21:03:16.136Z",
  "inheritedSpecIds": ["699b70325ae7d527cda5ffef", "699b705b5ae7d527cda5fff2"],
  "totals": {
    "errors": 1,
    "warnings": 2,
    "infos": 0,
    "passes": 7
  },
  "issues": [
    {
      "severity": "error",
      "type": "required",
      "message": "Required config not found",
      "spec": {
        "words": [
          {"type": "literal", "value": "ntp"},
          {"type": "literal", "value": "server"},
          {"type": "literal", "value": "ntp1.east.itential.com"}
        ],
        "evalMode": "required",
        "severity": "error"
      }
    }
  ]
}

Report fields:

• totals - counts of errors, warnings, infos, passes
• issues - array of violations, each with severity, type (required/disallowed), message, and the spec line that failed
• inheritedSpecIds - parent node specs that were also evaluated (shows inheritance in action)

Compliance Grading

Compliance reports can be graded to produce a score and letter grade.

Scoring formula:

Score = (totalNumPassLines / ((numOfErrorLines * errorWeight) + (numOfWarnLines * warnWeight) + (numOfInfoLines * infoWeight) + totalNumPassLines)) * 100

Default severity weights:

Default grade benchmarks:

Errors count double because they represent critical compliance violations.

Grade a report:

POST /configuration_manager/compliance_reports/grade/single

{
  "reportId": "699b70d95ae7d527cda5fff5"
}

Remediation

This skill does not remediate. NEVER wire a Configuration Manager remediation task that pushes golden-config/compliance-derived changes onto a device — auto or human-reviewed. The job of Golden Config is to define the standard, check devices against it, and grade the result. Applying a fix to a device is a separate, deliberately-designed config-push delivery with its own change control — not something Golden Config does automatically.

Prohibited tasks (never wire any of these into a workflow, never suggest them):

Note: updateNodeConfig is NOT prohibited — it authors the Golden Config node template (the standard), it doesn't touch a device. Likewise applyDeviceConfig/applyDeviceTemplate are generic config-apply tasks; they're fine for a deliberate push delivery but must never be wired to auto-apply changes derived from a compliance report.

There is no exception — not even when a spec asks for fully automatic remediation with no human in the loop. (convertChangesToConfig is also deprecated in Platform 6.5, removed in Platform 7 — see the deprecation notice — a dead end regardless of the prohibition.)

If a spec calls for remediation, do this instead:

1. This skill produces the compliance report — the list of violations (issues) per device.

2. Hand those violations to a config-push delivery built with /builder-agent: render the corrective configuration, then push it through the config-push mechanism available in the environment, with the normal dry-run → approval → commit pattern that any config change gets. Which push task to use depends on what the platform has configured — check the task catalog / adapters first, don't assume. Common options:

   • sendConfig (GatewayManager) — "Send configuration to inventory nodes" via an Automation Gateway
   • runService (GatewayManager) — run a gateway service such as the itential_cli Ansible role
   • netmikoSendConfig / netmikoSendConfigSet (AG) — netmiko-based config push
   • whatever vendor/SSH adapter the environment uses for config push

   See /builder-agent's config-push pattern and the Arista EOS "Push Configuration to Device - IAG" workflow in helpers/assets/vendor-arista-eos.json.

3. Re-run compliance (this skill) afterward to confirm the device is back in standard.

Helper JSON Templates

Developer Scenarios

1. Set up golden config compliance from scratch

1. POST /configuration_manager/configs → create tree with {name, deviceType}
2. PUT /configuration_manager/node/config → write template with prefixes, variables, regex
3. POST /configuration_manager/configs/{treeId}/initial/base → create child nodes
4. PUT /configuration_manager/node/config → set child node templates (inherited + overrides)
5. POST /configuration_manager/configs/{treeId}/initial/{nodePath}/devices → assign devices
6. POST /configuration_manager/compliance_reports → run compliance (returns batchId)
7. GET /configuration_manager/compliance_reports/batch/{batchId} → get report IDs
8. GET /configuration_manager/compliance_reports/details/{reportId} → see totals + issues
9. POST /configuration_manager/compliance_reports/grade/single → grade the report

2. Build config spec from existing device config

1. GET /configuration_manager/devices/{name}/configuration → get live config
2. POST /configuration_manager/generate/config_spec → auto-generate spec from raw config
3. Use the generated spec as a starting template for your golden config node

3. Import/Export for CI/CD

POST /configuration_manager/export/goldenconfigs → export tree as JSON
POST /configuration_manager/import/goldenconfigs → import to another environment