Requirements — IIQ Orphan Account Sweeper

Functional requirements

FR-1 — Read configuration from JSON

The script reads a JSON config file pointed to by --config <path>. The config declares:

• iiq.base_url — the IIQ REST root, e.g. https://identityiq.example.invalid/identityiq/rest.
• iiq.username — the service account that performs reads.
• iiq.password_env — the name of an environment variable holding the password (the password itself is never in the config).
• iiq.timeout_seconds — per-request timeout (default 30).
• applications — array of objects, each with name (IIQ Application name), enabled (bool), and an optional per-app service_account_pattern regex.
• hr.source — one of csv | rest | fixture.
• hr.path — file path (for csv / fixture) or URL (for rest).
• policy.termination_grace_days — accounts owned by an Identity terminated fewer than this many days ago are bucketed RECENT_TERMINATION (reported, not actioned).
• policy.global_service_account_pattern — regex applied across every app.
• output.results_csv — path for the per-account CSV.
• output.plans_dir — directory to write per-orphan ProvisioningPlan XML files.

FR-2 — Pull accounts per application

For each applications[i].enabled === true, the script issues:

GET {base_url}/accounts?application={name}&offset={n}&limit=500

It paginates until the response returns fewer than limit rows. Failure on any single application is logged and the sweep continues; the failing app appears in the run summary with a non-zero exit-code-contributing flag.

FR-3 — Pull identities once per run

The script issues a single paginated pull of identities with the projection it needs:

GET {base_url}/identities?fields=id,name,active,terminationDate,links&offset={n}&limit=500

Identities are cached in memory for the duration of the run.

FR-4 — Bucket every account

Each account is assigned exactly one of:

• HEALTHY — Link present, Identity active.
• ORPHAN_TERMED — Link present, Identity inactive, terminationDate ≤ today - termination_grace_days.
• RECENT_TERMINATION — Link present, Identity inactive, but within grace window.
• UNCORRELATED — no Link mapping the account to any Identity.
• SERVICE_ACCOUNT — account name matches any configured service-account regex (global or per-app).

FR-5 — Emit results CSV

The script writes output.results_csv with the columns:

application, native_identity, account_display_name, status,
linked_identity_id, linked_identity_name, identity_active,
termination_date, days_since_termination, last_login,
recommended_action, sweep_run_id

Status filter: every account is included so the file doubles as evidence of "what we saw."

FR-6 — Emit ProvisioningPlan XMLs

For every ORPHAN_TERMED row, the script writes a file output.plans_dir/<run-id>__<app>__<native_id_sanitized>.xml containing a valid IIQ ProvisioningPlan element with a single AccountRequest op="Disable" for the application + native identity. The XML is well-formed and namespaces match IIQ 8.x conventions.

FR-7 — Run summary to stdout

At end of run, print a fixed-format summary block:

• Per-app counts of each bucket.
• Total orphan-termed count.
• Total uncorrelated count.
• Path to the CSV and plans directory.
• Run ID.
• Exit code rationale.

FR-8 — No-network demo mode

With --no-network, the script reads accounts from _fixtures/accounts/<app>.json and identities from _fixtures/identities.json instead of hitting IIQ. This mode is for the bundled sample and for offline development.

FR-9 — Exit codes

• 0 — every enabled application swept successfully, zero unhandled exceptions.
• 1 — usage error (missing config, malformed JSON, unknown CLI flag).
• 2 — one or more applications failed to sweep (network/HTTP error). Successful apps still emit their rows.
• 3 — unexpected internal error.

FR-10 — Read-only by design

The script issues only GET requests against IIQ. There is no --apply flag. Submission of plans is a separate, gated process.

User stories

• As an IAM engineer, I want to schedule this script weekly so I get a fresh CSV on Monday morning showing every orphan account, without having to log into IIQ.
• As a SOX auditor, I want a file that proves the orphan-account control runs on a cadence, with a deterministic input config and a deterministic output for a given input.
• As a security operations analyst, I want the worst orphans (high-privilege apps, long-since-termed identities) to be visible in the run summary, not buried in the CSV.
• As an IAM director, I want one number — "open orphan accounts on terminated users" — that I can trend week-over-week and put on a dashboard.

Non-goals

• This is not a recertification engine. It does not re-run access reviews.
• It does not write back to IIQ. The output is evidence and plans; submission is a separate workflow.
• It does not modify connector configurations.
• It does not handle joiner / mover cases — only the leaver side of the lifecycle.

Success criteria

1. Running python script.py --config sample-config.json --no-network exits 0 and produces output that matches sample-output.txt.
2. The generated provisioning-plans/*.xml files validate as well-formed XML and contain exactly one AccountRequest per file.
3. The CSV row count equals the sum of bucket counts in the summary block.
4. No third-party Python packages are required (stdlib only — argparse, json, csv, re, pathlib, urllib.request, xml.etree.ElementTree, datetime, os, sys, logging).
5. No secret value appears anywhere in the file tree.