---
name: nowdev-ai-toolbox-environment-drift-audit
user-invocable: true
description: Safely and systematically audits configuration drift between two or more ServiceNow environments/instances that share the same Fluent application scope. Use this skill for environment comparison, drift audits, alignment checks, or pre-deployment safety checks. It delegates read-only `now-sdk` retrieval to `nowdev-ai-toolbox-servicenow-sdk` and aggregates configuration differences into high, medium, and low risk categories.
argument-hint: "[instance-a] [instance-b] [scope]"
---

# ServiceNow Environment Drift Audit

This skill provides a systematic workflow to audit, analyze, and report configuration drift between two or more ServiceNow environments/instances. Drift occurs when out-of-band updates, missing migrations, or environment-specific alterations cause configuration files (like Business Rules, ACLs, Roles, System Properties, Flows, or Scheduled Jobs) to diverge between instances.

---

## Core Principles

1. **Strictly Read-Only:** NEVER perform write, update, or delete operations on any ServiceNow instance while using this skill. Use `now-sdk` only for read-only retrieval.
2. **SDK Authority:** Load `nowdev-ai-toolbox-servicenow-sdk` before using `now-sdk`; it is the sole authority for command construction, flags, authentication aliases, output handling, pagination, and CLI troubleshooting.
3. **Deterministic Comparisons:** Compare configuration properties across instances using unique identifiers (`sys_id` for aligned Git/Fluent applications, or natural keys like `name` or `element` if sys_ids differ).
4. **Risk-Aware Categorization:** Group all detected discrepancies strictly by their deployment risk levels: **HIGH**, **MEDIUM**, and **LOW**.

---

## The Audit Workflow

Follow these steps precisely whenever triggered to audit drift:

### Step 1: Detect Scope and Target Instances
1. Read `now.config.json` or `package.json` in the workspace to retrieve the current scoped application's scope name (e.g. `x_abc_scope` or `x_123456_my_app`).
2. Ask the canonical SDK skill to resolve available connections.
3. Identify the target instances to compare. Use user-specified targets; otherwise ask the user to confirm the intended environments before retrieval.

### Step 2: Retrieve Critical Configuration
Ask `nowdev-ai-toolbox-servicenow-sdk` to perform the following read-only retrievals against every selected instance. Each retrieval must cover all records in scope; use deliberate pagination and report incomplete coverage.

| Table | Filter intent | Fields | Limit intent |
|---|---|---|---|
| `sys_script` | `sys_scope.scope` equals the discovered application scope | `sys_id,name,active,table,when,action_insert,action_update,action_delete,script,condition,sys_updated_on,sys_updated_by` | Complete scoped population |
| `sys_security_acl` | `sys_scope.scope` equals the discovered application scope | `sys_id,name,operation,active,advanced,script,condition,sys_updated_on,sys_updated_by` | Complete scoped population |
| `sys_security_acl_role` | ACL belongs to the discovered application scope | `sys_id,sys_security_acl,sys_user_role` | Complete scoped population |
| `sys_user_role` | `sys_scope.scope` equals the discovered application scope | `sys_id,name,description,sys_updated_on,sys_updated_by` | Complete scoped population |
| `sys_properties` | `sys_scope.scope` equals the discovered application scope | `sys_id,name,suffix,value,type,write_roles,read_roles,description,sys_updated_on,sys_updated_by` | Complete scoped population |
| `sys_hub_flow` | `sys_scope.scope` equals the discovered application scope | `sys_id,name,active,category,sys_updated_on,sys_updated_by` | Complete scoped population |
| `sysauto_script` | `sys_scope.scope` equals the discovered application scope | `sys_id,name,active,run_type,run_time,sys_updated_on,sys_updated_by` | Complete scoped population |

---

## Step 3: Compare Captured Data & Categorize Risk
Extract the JSON results and compare entries across the matched instances. Map records by `sys_id` when possible, checking for:
- Missing records (present in Environment A but absent in Environment B, indicating un-deployed or deleted artifacts).
- Value discrepancies (different active states, code scripts, operational fields, or configurations).

Assign each discovered difference to one of the three specified risk categories:

### HIGH RISK: Security and Access Control Alterations
High-risk differences represent direct security changes or properties that control access. Any mismatch here could leave production exposed, lock out users, or alter operations dangerously.
- **ACL Definitions (`sys_security_acl`):** Active state mismatches, script changes, advanced condition differences.
- **ACL Role Assignments (`sys_security_acl_role`):** Added or removed role-to-ACL associations, role-to-table grants.
- **Roles (`sys_user_role`):** Addition or removal of custom application roles.
- **Properties (`sys_properties`):** System property value changes (especially security/authentication properties, or those altering role privileges).

### MEDIUM RISK: Core Business Logic and Automations
Medium-risk differences represent logic, flows, or automated jobs that run silently in the background and can degrade process integrity.
- **Business Rules (`sys_script`):** Active/inactive state differences, script / timing condition differences, trigger field changes.
- **Flow Designer & Subflows (`sys_hub_flow`):** Active state differences (e.g. Active in dev but Draft on prod).
- **Scheduled script executions (`sysauto_script`):** Active state differences or scheduling/interval disagreements.
- **Automation artifacts:** Entirely missing/extra business rules, flows, or scheduled jobs in one of the compared environments.

### LOW RISK: Cosmetic and Meta-Information Differences
Low-risk differences have zero operational/security runtime effect but are descriptive.
- **Labels & Descriptions:** Form/field/property descriptions or role description differences.
- **Comments/formatting:** Comment updates inside script boxes, empty line spacing, or indentation differences that do not modify logic.
- **Timestamps:** Standard system fields like `sys_updated_on` or `sys_updated_by` differing (this is expected and should be highlighted simply as meta-drift, not high risk).

---

## Step 4: Generate the Environment Drift Report
Compile the comparison results into a structured Markdown format with tables. Always follow this template:

```markdown
# ServiceNow Application Environmental Drift Report
*Audited Application Scope: [scope_name]*
*Environments Compared: [alias_A_name] vs. [alias_B_name] (vs. others)*
*Audit Timestamp: [current_date_time]*

---

## 🚦 Overall Verdict
- **[CRITICAL DRIFT DETECTED / WARNING / SAFE TO DEPLOY]**
- *Brief summary of the safety risk or action needed before moving changes.*

---

## 🔥 HIGH RISK: Security & Access Differences
> Discrepancies in ACLs, Roles, or Security Properties. Review these before deployment!

| Environment | Table / Object | Record Name / ID | Property / Difference | Impact & Recommendation |
|---|---|---|---|---|
| [Alias] | sys_security_acl | [ACL Name] | [e.g. Active=false on Prod, Active=true on Dev] | Security bypass check required. |
| [Alias] | sys_security_acl_role | [ACL-Role Map] | [Role mapping missing on Prod] | Lock-out/Permission mismatch. |

*(If no HIGH risk differences, print "No high-risk configuration drift detected.")*

---

## ⚡ MEDIUM RISK: Logic, Flow & Automation Differences
> Discrepancies in Business Rules, Flows, or Scheduled Scripts.

| Environment | Table | Record Name | Difference / Trigger | Impact & Recommendation |
|---|---|---|---|---|
| [Alias] | sys_script | [BR Name] | [Active=true on Dev, Active=false on Prod] | Workflow will fail to process on Prod. |

*(If no MEDIUM risk differences, print "No medium-risk business logic drift detected.")*

---

## 📝 LOW RISK: Cosmetic & Metadata Differences
> Discrepancies in labels, descriptions, and metadata.

*(Short summary of any cosmetic discrepancies or matching alignment)*

---

## 📋 Recommended Action Items Checklist
- [ ] Align High-risk ACL permissions across all environments.
- [ ] Sync Business Rule/Flow active state differences.
- [ ] Verification complete.
```

---

## Summary of Guidelines for Agents Using This Skill
- Use `now-sdk` only for read-only retrieval; do not install, initialize, deploy, or mutate authentication. Delegate all mechanics to `nowdev-ai-toolbox-servicenow-sdk`.
- Resolve target connections before retrieval and ask the user when the intended instances are ambiguous.
- Request reference display values only when needed to interpret roles or ACLs; the canonical SDK skill determines output mechanics.
- Compare with both `sys_id` and `name` as identifiers.
- Ensure the overall verdict column is accurate and highlights the exact status.