{"id":49414377,"url":"https://github.com/itential/platform-atlas","last_synced_at":"2026-05-13T22:00:58.289Z","repository":{"id":350084749,"uuid":"1204926036","full_name":"itential/platform-atlas","owner":"itential","description":"A CLI tool that captures Itential configuration data from Itential deployments, validates against versioned rulesets, and generates compliance reports.","archived":false,"fork":false,"pushed_at":"2026-05-11T03:03:18.000Z","size":1862,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T05:33:45.684Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itential.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":"CLA.md"}},"created_at":"2026-04-08T13:18:44.000Z","updated_at":"2026-05-11T03:02:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/itential/platform-atlas","commit_stats":null,"previous_names":["itential/platform-atlas"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/itential/platform-atlas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fplatform-atlas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fplatform-atlas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fplatform-atlas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fplatform-atlas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itential","download_url":"https://codeload.github.com/itential/platform-atlas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fplatform-atlas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33001377,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"ssl_error","status_checked_at":"2026-05-13T13:14:51.610Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-29T02:15:33.902Z","updated_at":"2026-05-13T22:00:58.280Z","avatar_url":"https://github.com/itential.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Platform Atlas\n\n![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square\u0026logo=python\u0026logoColor=white)\n![License](https://img.shields.io/badge/license-%20%20GNU%20GPLv3%20-green?style=flat-square)\n\n\u003e Enterprise configuration auditing and compliance reporting for Itential Automation Platform\n\nPlatform Atlas is a comprehensive CLI tool that captures configuration data from Itential Automation Platform deployments and their dependencies, validates it against versioned rulesets, and generates professional compliance reports. It is designed for both Itential Customer Success teams conducting quarterly health assessments and customers performing self-service configuration validation.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Install and Setup](#install-and-setup)\n- [Initial Setup](#initial-setup)\n- [Configuration](#configuration)\n- [Environments](#environments)\n- [Kubernetes Deployments](#kubernetes-deployments)\n- [ControlMaster Transport (CyberArk PSMP)](#controlmaster-transport-cyberark-psmp)\n- [The Workflow](#the-workflow)\n- [Command Reference](#command-reference)\n- [Rulesets and Profiles](#rulesets-and-profiles)\n- [Multi-Tenant Mode](#multi-tenant-mode)\n- [Required Permissions](#required-permissions)\n- [Security](#security)\n- [Themes](#themes)\n- [Troubleshooting](#troubleshooting)\n- [Upgrading from Pre-1.5](#upgrading-from-pre-15)\n- [Support](#support)\n- [License](#license)\n\n---\n\n## Features\n\n- **Two Audit Tiers** — Choose between Standard (Platform OAuth + IAG4 API only, ~55 rules, no SSH/MongoDB/Redis required) and Extended (full infrastructure audit via SSH, MongoDB, Redis, Kubernetes, and Gateways, ~108 rules). Switch at any time with `platform-atlas tier set`.\n- **Automated Data Collection** — Connects via SSH, MongoDB, Redis, and Platform OAuth to capture configuration data from all components of an IAP deployment. If passwordless sudo is available, Atlas will automatically use it to read configuration files that the SSH user cannot access directly.\n- **Optional WebUI** — Browser-based interface (`platform-atlas-webui` wheel) for managing sessions, running captures, streaming live job output, and browsing reports — no CLI knowledge required.\n- **Multiple Rulesets** — Select from versioned, JSON schema-validated rulesets tailored to specific platform versions (e.g., Platform 6)\n- **Ruleset Profiles** — Environment-specific overlays (standalone, HA2, dev, prod, gateway4, gateway5) that enable or disable rules from the master ruleset\n- **~108 Validation Rules (Extended) / ~55 (Standard)** — Covering Redis, MongoDB, Platform, Gateway4, and Gateway5 across critical, warning, and info severity levels\n- **Extended Validation** — Decorator-based checks that run outside the standard ruleset structure for health, adapter, and version analysis\n- **Rule Chaining** — Rules can depend on other rules, so downstream checks are automatically skipped when a dependency fails\n- **Dynamic Rules** — Limited computed values inside rules for proper comparison against runtime configuration\n- **Professional HTML Reports** — Full HTML/CSS/JS reports with the Atlas Horizon design system, supporting dark and light themes with W3C-compliant markup\n- **Session Diff Engine** — Compare two audit sessions side-by-side to track configuration drift, regressions, and fixes over time\n- **Session Management** — Organize captures, validations, and reports into named sessions with metadata tracking. Each session binds an environment, ruleset, tier, and profile at creation — switching sessions restores the full context automatically\n- **Guided Manual Collection** — Interactive fallback prompts for environments where automated capture cannot reach certain components. Supports batch directory import (`--import-dir`) for importing all pre-collected files at once without interactive prompts — re-runnable to incrementally add data.\n- **Multi-Tenant Mode** — Itential staff can import and manage capture data from multiple customer organizations in a single installation\n- **Named Environments** — Define multiple deployment targets (dev, staging, production) as independent environment files, each with its own organization name, connection details, topology, and scoped credentials\n- **Deployment Topology** — Models standalone, HA2, and custom deployment architectures with configurable capture scope\n- **Secure Credential Storage** — Sensitive credentials stored in the OS keyring (macOS Keychain, Windows Credential Locker, Linux Secret Service) or Hashicorp Vault, scoped per environment, never in config files\n- **Air-Gapped Support** — Operates entirely offline after installation; no internet access required for capture, validation, or reporting\n- **Multiple Export Formats** — HTML, CSV, and JSON report output with session export and redaction support\n- **Three-Report System** — `session run report` always generates all three HTML reports in a single pass: `03_report.html` (compliance), `04_operational.html` (logs + MongoDB pipelines), and `05_arch.html` (architecture \u0026 maintenance); all three share a header nav bar and the compliance report opens automatically in the browser\n- **MongoDB Aggregation Pipelines** — After capture, Atlas prompts whether to run aggregation pipelines against the Platform's MongoDB database for the operational report; pipeline definitions are extensible via user-defined JSON files in `~/.atlas/pipelines/`\n\n## Requirements\n\n- Python 3.11 or higher\n- Platform OAuth service account with read-only API access *(all tiers)*\n- OS keyring backend available (macOS Keychain, GNOME Keyring, KWallet, or Windows Credential Locker), or Hashicorp Vault with KV v2 secrets engine *(all tiers)*\n- SSH access to target nodes (key-based authentication recommended) *(Extended tier only)*\n- MongoDB user with `clusterMonitor` (admin) + `read` on the Platform database *(Extended tier only)*\n- Read-only Redis user with limited ACL permissions *(Extended tier only)*\n\n## Install and Setup\n\nPlatform Atlas is distributed as two Python wheel packages — the core CLI and an optional WebUI. Install inside a dedicated virtual environment on the workstation you use to access your IAP environment.\n\n```bash\n# Create and activate a virtual environment\npython3 -m venv atlas-venv\nsource atlas-venv/bin/activate\n\n# Install the CLI (required)\npip3 install -U platform_atlas-\u003cversion\u003e-py3-none-any.whl\n\n# Install the WebUI (optional — adds the browser interface)\npip3 install -U platform_atlas_webui-\u003cversion\u003e-py3-none-any.whl\n```\n\nVerify the installation:\n\n```bash\nplatform-atlas --version\n```\n\n### Starting the WebUI\n\nIf you installed the WebUI wheel, launch it with:\n\n```bash\nplatform-atlas-webui\n```\n\nThis starts a local server and opens the interface in your browser. The WebUI shares the same `~/.atlas/` configuration directory as the CLI — no separate setup required.\n\n### Credential Storage (OS Keyring)\n\nPlatform Atlas stores sensitive credentials (MongoDB, Redis, Platform OAuth, SSH passphrases, Gateway passwords) in your operating system's secure credential store via the `keyring` library — never in config files on disk. Each environment's secrets are scoped under `platform-atlas/\u003cenv-name\u003e` so production credentials are completely isolated from dev/staging credentials.\n\n| Platform | Backend used |\n|---|---|\n| macOS | Keychain (built-in) |\n| Windows | Credential Locker (built-in) |\n| Linux (desktop) | GNOME Keyring / KWallet via SecretService |\n| Linux (headless) | Encrypted file backend (configure manually — see below) |\n\n**Reconfigure or rotate credentials at any time:**\n\n```bash\nplatform-atlas config credentials\n```\n\nThis is the canonical command for adding, updating, or rotating any credential — Platform OAuth client secret, MongoDB/Redis URIs, SSH key passphrases, Gateway4 password, or Vault auth tokens. It writes to the active environment's keyring scope (or to your Vault backend, depending on `credential_backend`). Use it whenever:\n\n- A credential has been rotated upstream and Atlas connections start failing\n- You're switching backends (`keyring` ↔ `vault`)\n- You set up a new SSH key with a passphrase\n- You need to add a credential that wasn't collected during the original `env create` flow (e.g. retrofitting a Gateway4 password onto an existing environment)\n\nYou do **not** need to recreate the environment to update credentials.\n\n### Credential Storage (Headless Servers)\n\nPlatform Atlas is generally to be used on a Workstation PC, but if needed to install on a server this can be done. On headless Linux servers without a desktop environment, the default keyring backend has no encryption. Atlas will warn you about this during setup if it detects an insecure backend.\n\nTo set up encrypted credential storage, install the following packages:\n\n```bash\npip3 install keyring keyrings.alt pycryptodome SecretStorage\n```\n\nIf `SecretStorage` fails to build, you may also need:\n\n```bash\ndnf install libsecret-devel python3-dbus\n```\n\nThen configure keyring to use the encrypted file backend:\n\n```bash\nmkdir -p ~/.config/python_keyring\ncat \u003e ~/.config/python_keyring/keyringrc.cfg \u003c\u003c EOF\n[backend]\ndefault-keyring=keyrings.alt.file.EncryptedKeyring\nEOF\n```\n\nYou can verify the backend is active with:\n\n```bash\npython3 -c \"import keyring; print(keyring.get_keyring())\"\n```\n\nThis should output `EncryptedKeyring`. The first time Atlas stores a credential, you will be prompted to create a master password for the encrypted keyring file. After that, run `platform-atlas config credentials` to populate the encrypted store with your environment's secrets.\n\n### Credential Storage (Hashicorp Vault)\n\nPlatform Atlas can use Hashicorp Vault as a read-only credential backend instead of the OS keyring. In this mode, Atlas reads credentials from a KV v2 secrets engine at runetime but never writes to Vault - secrets are managed externally through the Vault UI, CLI, or API calls outside of Atlas.\n\nVault connection settings (URL, authe methd, token or AppRole credentials, mount path) are stored in the OS keyring under a `vault_` prefix, keeping them off disk entirely.\n\nTo configure Vault as the credential backend, run the setup wizard and select \"vault\" when prompted:\n```bash\nplatform-atlas config init\n```\n\nOr reconfigure credentials for an existing installation:\n```bash\nplatform-atlas config credentials\n```\n\nAtlas supports five Vault authentication methods, grouped by use case:\n\n**Standard — credentials stored in the OS keyring:**\n\n| Method | What to provide | When to use |\n|---|---|---|\n| **Token** | A static Vault token | Simple setups; token is long-lived or manually rotated |\n| **AppRole** | `role_id` + static `secret_id` | Machine-to-machine auth; secret_id does not rotate |\n\n**Automated / rotating credentials — no long-lived secret stored in Atlas:**\n\n| Method | What to provide | When to use |\n|---|---|---|\n| **AppRole (Wrapped)** | `role_id` + response-wrapped token | Pipeline or Vault admin generates a fresh wrapped secret_id on a schedule; token is consumed on first use |\n| **Token (file)** | Path to a token sink file | Vault Agent runs on the same host, renews the token continuously, and writes it to a file; Atlas reads the file at runtime |\n| **Token (env)** | *(none stored)* | Pipeline or orchestrator sets `VAULT_TOKEN` before running Atlas; Atlas reads it at runtime |\n\nFor the **Token (file)** method, your Vault admin configures Vault Agent as a system service (e.g. a systemd unit) once. After that, token rotation is entirely hands-off — Atlas always finds a valid token in the file regardless of when it runs.\n\nFor the **Token (env)** method, ensure `VAULT_TOKEN` is set in the environment before invoking Atlas. In systemd, this is typically an `EnvironmentFile=` directive; in CI pipelines, a secret injection step.\n\nSecrets should be stored in Vault as key-value pairs at the configured path (default: `secret/data/platform-atlas`):\n\n| Vault Key | Description |\n| ---|---|\n| `platform_client_secret` | Platform OAuth client secret (required) |\n| `mongo_uri` | MongoDB connection URI |\n| `redis_uri` | Redis connection URI |\n| `ssh_key_passphrase` | SSH key passphrase (if applicable) |\n\nYou can verify the backend is active with:\n```bash\nplatform-atlas config show\n```\n\nThe credential backend type will be displayed in the configuration output. Preflight checks will verify Vault connectivity and confirm that required secrets are present.\n\n## Initial Setup\n\nTo configure Platform Atlas for the first time, run it without any arguments:\n\n```bash\nplatform-atlas\n```\n\nIf no configuration file exists, this will launch an interactive setup wizard with two phases:\n\n1. **Global Settings** — Organization name, theme, and preferences that apply across all environments. Saved to `~/.atlas/config.json`.\n2. **First Environment** — Connection details, credential backend, and deployment topology for your first target deployment. Saved to `~/.atlas/environments/\u003cname\u003e.json`.\n\nYou can also run the setup wizard directly at any time:\n\n```bash\nplatform-atlas config init\n```\n\nGlobal settings are stored at `~/.atlas/config.json`. Environment-specific configuration is stored in `~/.atlas/environments/`. Credentials are stored separately in your OS keyring (scoped per environment under `platform-atlas/\u003cenv-name\u003e`) or read from Hashicorp Vault if configured as the credential backend.\n\n## Configuration\n\n### Global Configuration\n\nGlobal settings that apply across all environments are stored in `~/.atlas/config.json`:\n\n```json\n{\n    \"organization_name\": \"Acme Corp\",\n    \"active_environment\": \"production\",\n    \"verify_ssl\": false,\n    \"dark_mode\": true,\n    \"theme\": \"horizon-prism\",\n    \"extended_validation_checks\": true,\n    \"multi_tenant_mode\": false,\n    \"debug\": false\n}\n```\n\n### Environment Configuration\n\nEach environment file (`~/.atlas/environments/\u003cn\u003e.json`) contains the connection and deployment details for one target:\n\n```json\n{\n    \"name\": \"production\",\n    \"organization_name\": \"Acme Corp\",\n    \"description\": \"Production IAP cluster - US East\",\n    \"platform_uri\": \"https://iap.acme.com:3443\",\n    \"platform_client_id\": \"6920cb7d61910148410489f9\",\n    \"credential_backend\": \"keyring\",\n    \"deployment\": {\n        \"mode\": \"standalone\",\n        \"capture_scope\": \"primary_only\",\n        \"nodes\": [\n            {\n                \"role\": \"all\",\n                \"host\": \"iap-01.acme.com\",\n                \"ssh_user\": \"atlas\",\n                \"ssh_port\": 22\n            }\n        ]\n    }\n}\n```\n\nWhen an environment is active, its fields are merged on top of the global config at load time. Credentials in the OS keyring are scoped to `platform-atlas/\u003cenv-name\u003e`, keeping each environment's secrets isolated.\n\n### Configuration Commands\n\n```bash\nplatform-atlas config show              # Display current config (redacted)\nplatform-atlas config show --full       # Display config including secrets\nplatform-atlas config credentials       # Manage stored credentials\nplatform-atlas config deployment        # Reconfigure deployment topology\nplatform-atlas config theme             # Switch color theme\n```\n\n## Environments\n\nEnvironments let you define and switch between multiple IAP deployments (dev, staging, production) without re-running setup. Each environment is a JSON file under `~/.atlas/environments/` with its own Platform URI, credentials, and deployment topology.\n\n### Managing Environments\n\n```bash\n# List all environments (shows which is active)\nplatform-atlas env list\n\n# Create a new environment (interactive wizard)\nplatform-atlas env create\n\n# Create by copying an existing environment\nplatform-atlas env create staging --from production\n\n# Switch the active environment\nplatform-atlas env switch staging\n\n# Show details of an environment\nplatform-atlas env show production\n\n# Edit an environment file in $EDITOR\nplatform-atlas env edit staging\n\n# Remove an environment\nplatform-atlas env remove dev\n```\n\n### Overriding for a Single Command\n\nUse the `--env` flag to target a specific environment without switching the global active:\n\n```bash\nplatform-atlas --env dev preflight\nplatform-atlas --env staging session run capture\n```\n\n### Environment Resolution\n\nWhen Atlas starts, the active environment is resolved in this order:\n\n1. `--env` CLI flag (highest priority)\n2. `ATLAS_ENV` environment variable\n3. `active_environment` field in `config.json`\n4. No environment — legacy mode using `config.json` directly\n\n### Backward Compatibility\n\nIf no environments exist (e.g., an existing installation that predates this feature), Atlas uses `config.json` as-is — the same behavior as before. The environment system only activates when environments are explicitly created.\n\n### Deployment Modes\n\nPlatform Atlas supports three deployment architectures:\n\n- **Standalone** — Single-instance IAP with co-located or split MongoDB, Redis, and optional Gateway. Uses an `all` role for all-in-one nodes, or individual `iap`, `mongo`, `redis`, `iag` roles for split configurations.\n- **HA2** — Highly Available deployments with 2+ IAP nodes, 3-node MongoDB replica set, 3-node Redis Sentinel cluster, and optional Gateway nodes.\n- **Custom** — Free-form node list with manually assigned collector modules per node.\n\n### Capture Scope\n\nThe `capture_scope` setting controls how many nodes the capture engine connects to:\n\n- **primary_only** (default) — One node per role. Minimal connections for standard audits.\n- **all_nodes** — Every node in the topology. Used when you need full coverage across all replicas and cluster members.\n\n## Tiers\n\nStarting in v1.7, Atlas operates in one of two modes:\n\n| | Standard | Extended |\n|---|---|---|\n| **Collectors** | Platform OAuth, IAG4 API | All Standard + SSH, MongoDB, Redis, Kubernetes, Gateway5 |\n| **Rules** | ~55 | ~108 |\n| **SSH required** | No | Yes |\n| **MongoDB / Redis required** | No | Yes |\n| **Best for** | Application-layer audits, quick checks, restricted environments | Full infrastructure compliance audits |\n\nFresh installs default to **Standard**. Upgrades from 1.6.x default to **Extended** to preserve existing behavior.\n\n### Tier Commands\n\n```bash\nplatform-atlas tier show              # Show active tier and what is enabled\nplatform-atlas tier set standard      # Switch to Standard (non-interactive)\nplatform-atlas tier set extended      # Switch to Extended (non-interactive)\nplatform-atlas tier upgrade           # Guided Standard → Extended flow\nplatform-atlas tier downgrade         # Guided Extended → Standard flow\n```\n\nUse the `--tier` flag to override the tier for a single command without changing the persisted setting:\n\n```bash\nplatform-atlas --tier standard session run capture\n```\n\nSessions bind the active tier at creation time. The tier is displayed in session metadata and reports. Cross-tier diffs are flagged with a notice banner.\n\n---\n\n## Kubernetes Deployments\n\nKubernetes deployments use the `KubernetesCollector` instead of SSH-based collectors. Data comes from two sources: Helm `values.yaml` files (declarative config) and live `kubectl` commands (runtime state). No SSH access is required.\n\n### Configuring a Kubernetes Environment\n\nWhen creating an environment, select **Kubernetes** as the deployment mode. The setup wizard will prompt for:\n\n| Field | Purpose |\n|---|---|\n| `values_yaml_path` | Path to the IAP Helm `values.yaml` |\n| `iag5_values_yaml_path` | Path to the IAG5 `values.yaml` (optional) |\n| `use_kubectl` | Enable live `kubectl` collection |\n| `kubectl_context` | kubectl context name (leave blank for current context) |\n| `kubectl_namespace` | Kubernetes namespace (default: `default`) |\n\nThese fields are also editable after setup via `platform-atlas env edit` or the WebUI **Environments** form.\n\n### Data Source Priority\n\nFor Kubernetes environments, each data type is collected in this order, using the first source that succeeds:\n\n1. **Platform OAuth API** — health, version, application status, runtime configuration\n2. **kubectl `printenv`** (if `use_kubectl: true`) — live environment variables from inside a running IAP pod\n3. **values.yaml** — declarative Helm configuration as a static fallback\n\nMongoDB and Redis data requires the protocol collectors (pymongo / redis-py) to be reachable. If MongoDB and Redis are external managed services (e.g., AWS Atlas, ElastiCache), the Mongo and Redis rule categories will show as **SKIP** in the report — this is expected and not an error.\n\n### kubectl Rule Fallbacks\n\nThe following rules have an `alt_path` that Atlas uses when the primary data source (Platform OAuth API) is unavailable. The `alt_path` data comes from `kubectl exec \u003cpod\u003e -- printenv` — the live `ITENTIAL_*` environment variables baked into the running pod.\n\n**Group 1 — Pod environment variables (`ITENTIAL_*` → `platform.config_file.*`)**\n\n| Rule | Primary path | kubectl alt_path | Pod env var |\n|---|---|---|---|\n| Platform Default User | `platform.config.default_user_enabled.value` | `platform.config_file.default_user_enabled` | `ITENTIAL_DEFAULT_USER_ENABLED` |\n| Platform Core Logging Level | `platform.config.log_level.value` | `platform.config_file.log_level` | `ITENTIAL_LOG_LEVEL` |\n| Server ID | `platform.config.server_id.value` | `platform.config_file.server_id` | `ITENTIAL_SERVER_ID` |\n| Mongo Auth Enabled | `platform.config.mongo_auth_enabled.value` | `platform.config_file.mongo_auth_enabled` | `ITENTIAL_MONGO_AUTH_ENABLED` |\n| Mongo TLS Enabled | `platform.config.mongo_tls_enabled.value` | `platform.config_file.mongo_tls_enabled` | `ITENTIAL_MONGO_TLS_ENABLED` |\n| Log Max Files | `platform.config.log_max_files.value` | `platform.config_file.log_max_files` | `ITENTIAL_LOG_MAX_FILES` |\n| Log File Max Size | `platform.config.log_max_file_size.value` | `platform.config_file.log_max_file_size` | `ITENTIAL_LOG_MAX_FILE_SIZE` |\n| Webserver HTTPS Enabled | `platform.config.webserver_https_enabled.value` | `platform.config_file.webserver_https_enabled` | `ITENTIAL_WEBSERVER_HTTPS_ENABLED` |\n| Webserver HTTP Enabled | `platform.config.webserver_http_enabled.value` | `platform.config_file.webserver_http_enabled` | `ITENTIAL_WEBSERVER_HTTP_ENABLED` |\n| Webserver Timeout | `platform.config.webserver_timeout.value` | `platform.config_file.webserver_timeout` | `ITENTIAL_WEBSERVER_TIMEOUT` |\n\n**Group 2 — kubectl system data (`system.kubernetes.*`)**\n\nThese fallbacks come from files and commands read directly inside the running pod, rather than environment variables. They are collected automatically whenever `use_kubectl: true` and an IAP pod is found.\n\n| Rule | Primary path | kubectl alt_path | Source inside pod |\n|---|---|---|---|\n| Platform Version | `platform.health_server.version` | `system.kubernetes.platform_release_version` | `cat /opt/itential/platform/server/release_metadata.json` |\n| Node Version | `platform.health_server.versions.node` | `system.kubernetes.node_version` | `node --version` |\n| Gateway Manager Version Check | `platform.application_status.results.GatewayManager.version` | `system.kubernetes.installed_services.app-ag_manager.version` | `cat .../services/app-ag_manager/package.json` |\n\n\u003e **Debug logging:** When `--debug` is enabled (or `\"debug\": true` in `config.json`), Atlas logs every `kubectl` command it runs, the exit code, elapsed time, and any stderr output to `~/.atlas/atlas.log`. This makes it straightforward to verify which commands fired and whether they succeeded.\n\n---\n\n## ControlMaster Transport (CyberArk PSMP)\n\nSome environments route SSH through a Privileged Access Management (PAM) gateway such as CyberArk PSMP, where direct key-based SSH to the target server isn't possible — authentication requires MFA (YubiKey OTP, RADIUS, etc.) and goes through a jump host rather than direct to the server.\n\nAtlas supports **ControlMaster transport** for these environments. Instead of opening a fresh SSH connection for every collector, Atlas piggybacks on a single pre-authenticated SSH session that you open manually before running a capture. Once the master session is established and MFA is satisfied, Atlas multiplexes all of its connections through it with no further authentication prompts.\n\n\u003e **Scope:** ControlMaster applies to the **Platform (IAP) node only**. MongoDB and Redis nodes still use regular SSH — configure a direct-access user for them as described in the [SSH Setup Guide](GUIDES/SSH_SETUP_GUIDE.md).\n\n### When to Use It\n\n- Your IAP server is behind CyberArk PSMP or a similar PAM gateway\n- SSH to the IAP node requires MFA (YubiKey, RADIUS, smart card) that Atlas cannot automate\n- Direct key-based SSH to the IAP node is not permitted by policy\n\n### Step 1: Open the ControlMaster Session\n\nBefore running Atlas, open the master connection once from your workstation. This is the step that triggers MFA — complete it interactively, then Atlas takes over:\n\n```bash\nssh -M -S /tmp/atlas-cm.sock \\\n    -o ControlPersist=10m \\\n    -o StrictHostKeyChecking=no \\\n    -o UserKnownHostsFile=/dev/null \\\n    -fN user@target-host@psmp-gateway.example.com\n```\n\n| Flag | Purpose |\n|---|---|\n| `-M -S /tmp/atlas-cm.sock` | Create a ControlMaster socket at that path |\n| `-o ControlPersist=10m` | Keep the socket alive for 10 minutes after the connection — enough for a full capture |\n| `-fN` | Background the process (`-f`) and open no remote command (`-N`) |\n| `user@target-host@psmp-gateway` | CyberArk PSMP format: `\u003cuser\u003e@\u003ctarget-ip-or-host\u003e@\u003cpsmp-gateway-host\u003e` |\n\nYou will be prompted for MFA (password, YubiKey tap, etc.) during this step. Once complete, the master session runs silently in the background.\n\n**Verify the socket is working:**\n\n```bash\nssh -S /tmp/atlas-cm.sock \\\n    -o StrictHostKeyChecking=no \\\n    -o UserKnownHostsFile=/dev/null \\\n    user@target-host@psmp-gateway.example.com \\\n    \"echo atlas-ok \u0026\u0026 whoami \u0026\u0026 hostname\"\n```\n\nIf you see `atlas-ok` plus the username and hostname, Atlas will be able to connect.\n\n### Step 2: Configure Atlas\n\n**CLI — during environment setup:**\n\nWhen the setup wizard asks how Atlas should connect to the Platform (IAP) server, select **ControlMaster**. You will be prompted for:\n\n- **Socket path** — path to the `-S` socket file (e.g. `/tmp/atlas-cm.sock`)\n- **SSH destination** — the full destination string exactly as used in the `ssh -M` command (e.g. `user@target-host@psmp-gateway.example.com`)\n\n**WebUI — in the Environment form:**\n\nUnder **Topology → Platform (IAP) connection type**, select **ControlMaster — CyberArk PSMP / jump host**. Two additional fields appear:\n- **ControlMaster socket path** — same as above\n- **SSH destination** — same as above\n\n### Step 3: Run Atlas\n\nWith the master session open, run Atlas normally:\n\n```bash\nplatform-atlas session run capture\n```\n\nAtlas will connect through the socket without prompting for MFA. If the socket has expired (closed or timed out), Atlas will print the exact `ssh -M` command to re-open it.\n\n---\n\n## The Workflow\n\nPlatform Atlas follows a structured sequence: **Preflight → Capture → Validate → Report**.\n\n### 1. Preflight\n\nBefore capturing anything, verify that all configured connections are reachable:\n\n```bash\nplatform-atlas preflight\n```\n\nThis checks SSH connectivity to all target nodes, MongoDB and Redis access, Platform API reachability, and required file permissions. If something fails, it tells you what and why.\n\n### 2. Create a Session\n\nEverything runs inside a session. A session is a directory that holds your capture data, validation results, and reports together under a single name. When you create a session, you select an environment, ruleset, and profile — these are bound to the session so that switching sessions later restores the full context.\n\n```bash\nplatform-atlas session create prod-audit-q1\n```\n\nThe interactive wizard prompts you to select an environment, ruleset, and profile. You can also specify them directly:\n\n```bash\nplatform-atlas session create prod-audit-q1 --env production --ruleset p6-master-ruleset --profile p6-prod-standalone-gateway4\n```\n\nTo switch between sessions (also restores the bound environment, ruleset, and profile):\n\n```bash\nplatform-atlas session switch\nplatform-atlas session list\nplatform-atlas session show prod-audit-q1\n```\n\nTo edit session bindings before capture begins:\n\n```bash\nplatform-atlas session edit\n```\n\n\u003e **Note:** In versions before 1.5, environments, rulesets, profiles, and sessions were managed independently. Starting in v1.5, sessions bind all of these together — one switch, full context restored. The `ruleset setup`, `ruleset load`, and `ruleset profile set` commands still work for ad-hoc use, but the session creation wizard is the recommended workflow.\n\n### 3. Capture\n\nThe capture engine connects to your targets and collects configuration data from all enabled modules:\n\n```bash\nplatform-atlas session run capture\n```\n\nYou will see a live progress display as each collector runs. If one module fails, the rest continue — you will not lose your entire capture because a single system timed out. Failed modules will prompt guided fallback collection unless skipped.\n\nThe capture order is always: **Preflight → Automated Capture → Manual Prompts → JSON Integrity Check → Customer Summary**.\n\nTo capture only specific modules:\n\n```bash\nplatform-atlas session run capture --modules system mongo redis\n```\n\nTo use fully manual collection (for air-gapped or restricted environments):\n\n```bash\nplatform-atlas session run capture --manual\n```\n\nIf you have pre-collected data files in a directory, you can batch-import them all at once instead of going through the interactive prompts:\n\n```bash\nplatform-atlas session run capture --manual --import-dir ~/atlas-capture/\n```\n\nAtlas matches files by name and loads them automatically. Any files it doesn't recognize are skipped. You can re-run the same command after adding more files to the directory — progress is cumulative. See `MANUAL-COLLECTION-GUIDE.md` for the expected filenames and the commands to collect each file.\n\n### 4. Validate\n\nValidation runs your captured data through the loaded ruleset. Each rule has a type, operator, target path, and expected value. Rules can depend on other rules — if a dependency fails, the downstream rule is automatically skipped.\n\n```bash\nplatform-atlas session run validate\n```\n\nResults are stored as `validation.parquet` in the session directory using Apache Arrow for efficient storage and retrieval.\n\nSeverity levels are **critical**, **warning**, and **info**.\n\n### 5. Report\n\nGenerate a professional HTML report from the validation results:\n\n```bash\nplatform-atlas session run report\n```\n\nReports include compliant/non-compliant breakdowns by category and severity, detailed results with expected vs. actual values, extended validation findings, and session metadata. The report opens automatically in your default browser.\n\nTo generate in other formats:\n\n```bash\nplatform-atlas session run report --format csv\nplatform-atlas session run report --format json\n```\n\n### 6. Reports\n\n`session run report` generates all three HTML reports in a single pass:\n\n| File | Contents |\n|---|---|\n| `03_report.html` | Compliance: overall score, category breakdown, rule results, extended validation findings |\n| `04_operational.html` | Operational: platform/webserver/MongoDB log analysis and aggregation pipeline results |\n| `05_arch.html` | Architecture \u0026 Maintenance: adapter states, Redis ACL, index status, IAG paths, and architecture overview |\n\nThe compliance report opens automatically in your browser. All three reports share a header navigation bar linking to each other.\n\n**MongoDB Aggregation Pipelines**\n\nAfter capture completes, Atlas prompts whether to run MongoDB aggregation pipelines for the operational report. These query live workflow and task data from the Platform database to produce execution statistics, top workflows, and runtime metrics. If you decline, the operational report still generates — it will contain log analysis only with a notice in the pipeline section.\n\nYou can extend the pipeline output by adding your own pipeline JSON files to `~/.atlas/pipelines/` — they are discovered and executed automatically.\n\n### Run Everything at Once\n\nTo execute the full capture → validate → report pipeline in one command:\n\n```bash\nplatform-atlas session run all\n```\n\n### Session Diff\n\nCompare two sessions to see what changed between audits:\n\n```bash\nplatform-atlas session diff baseline-q4 latest-q1\n```\n\nThe diff report classifies each rule as Fixed, Regressed, Unchanged, New, Removed, Changed, or Skipped.\n\n## Command Reference\n\n### Session Commands\n\n| Command | Description |\n|---|---|\n| `session create \u003cn\u003e` | Create a new session (binds environment, ruleset, and profile) |\n| `session create \u003cn\u003e --env --ruleset --profile` | Create with explicit bindings (skips prompts) |\n| `session list` | List all sessions with environment, org, ruleset, and status |\n| `session show [name]` | Show session details and bindings |\n| `session active [name]` | Show or set the active session (restores full context) |\n| `session switch [name]` | Switch sessions (alias for active) |\n| `session edit [name]` | Edit session bindings (only before capture) |\n| `session run \u003cstage\u003e` | Run a workflow stage (capture, validate, report, all) |\n| `session run capture --manual` | Interactive guided collection for air-gapped environments |\n| `session run capture --manual --import-dir \u003cdir\u003e` | Batch import capture files from a directory |\n| `session run report` | Generate all three HTML reports (compliance, operational, architecture) |\n| `session export [name]` | Package session for delivery (zip or tar.gz) |\n| `session delete \u003cn\u003e` | Permanently remove a session |\n| `session diff \u003cbaseline\u003e \u003clatest\u003e` | Compare two sessions |\n| `session repair [name]` | Backfill missing metadata on pre-1.5 sessions |\n\n### Ruleset Commands\n\n| Command | Description |\n|---|---|\n| `ruleset setup` | Interactive ruleset and profile selection (recommended) |\n| `ruleset list` | List available rulesets |\n| `ruleset load \u003cid\u003e` | Load and activate a ruleset |\n| `ruleset info [id]` | Show ruleset details |\n| `ruleset active` | Show active ruleset |\n| `ruleset clear` | Deactivate current ruleset |\n| `ruleset rules [id]` | Display all rules in a ruleset |\n| `ruleset profile list` | List available profiles |\n| `ruleset profile set \u003cid\u003e` | Set a profile overlay |\n| `ruleset profile active` | Show active profile |\n| `ruleset profile clear` | Clear active profile |\n\n### Config Commands\n\n| Command | Description |\n|---|---|\n| `config init` | Run the interactive setup wizard |\n| `config show` | Display current configuration (redacted) |\n| `config credentials` | Manage keyring credentials |\n| `config deployment` | Reconfigure deployment topology |\n| `config theme` | Switch color theme |\n\n### Environment Commands\n\n| Command | Description |\n|---|---|\n| `env list` | List all environments with organization and active status |\n| `env create [name]` | Create a new environment (interactive wizard) |\n| `env create [name] --from \u003cenv\u003e` | Copy from an existing environment |\n| `env switch [name]` | Switch environment and offer to switch to a bound session |\n| `env show [name]` | Show environment details |\n| `env edit [name]` | Edit environment settings (org name, URIs, topology, etc.) |\n| `env remove \u003cn\u003e` | Delete an environment |\n\n### Tier Commands\n\n| Command | Description |\n|---|---|\n| `tier show` | Show the active tier and what is enabled |\n| `tier set \u003ctier\u003e` | Set the global tier (`standard` or `extended`) |\n| `tier upgrade` | Guided Standard → Extended upgrade flow |\n| `tier downgrade` | Guided Extended → Standard downgrade flow |\n\n### Other Commands\n\n| Command | Description |\n|---|---|\n| `preflight` | Run connectivity checks against all configured services |\n| `guide` | View the built-in help guide |\n| `--version` | Display version |\n| `--debug` | Enable debug mode with verbose logging |\n| `--env \u003cname\u003e` | Use a specific environment for this command |\n| `--tier \u003ctier\u003e` | Override the active tier for this command only |\n\n## Rulesets and Profiles\n\n### Rulesets\n\nA ruleset is a versioned JSON file containing an array of validation rules. Each rule defines a target path in the captured data, a validation type and operator, an expected value, and pass/fail messages.\n\nPlatform Atlas ships with the **Platform 6 Master Ruleset** (`p6-master-ruleset`) containing 105 rules across five categories:\n\n| Category | Rules | Coverage |\n|---|---|---|\n| Platform | 47 | Application settings, adapters, services, properties |\n| Gateway5 | 23 | IAG5 configuration, health, version checks |\n| Redis | 16 | Server config, memory, persistence, replication, ACLs |\n| Gateway4 | 11 | Venv packages, sync config, database settings |\n| MongoDB | 8 | Server status, version, replication, connection settings |\n\nSeverity breakdown: 15 critical, 61 warning, 29 info.\n\nThere is also an included **IAP 2023.x Master Ruleset** (`2023-master-ruleset`) in the configuration file for IAP 2023.x Support for Atlas. Please see `3. Load a Ruleset and Profile` for more information on using this if needed.\n\n### Profiles\n\nProfiles are lightweight overlays that enable or disable specific rules from the master ruleset. This avoids maintaining separate ruleset copies for each environment type.\n\nAvailable profiles for Platform 6:\n\n| Profile | Description |\n|---|---|\n| `p6-prod-standalone-gateway4` | Production standalone with Gateway4 |\n| `p6-prod-standalone-gateway5` | Production standalone with Gateway5 |\n| `p6-prod-standalone-no-gateway` | Production standalone without Gateway |\n| `p6-prod-ha2-gateway4` | Production HA2 with Gateway4 |\n| `p6-prod-ha2-gateway5` | Production HA2 with Gateway5 |\n| `p6-prod-ha2-no-gateway` | Production HA2 without Gateway |\n| `p6-dev-standalone-gateway4` | Development standalone with Gateway4 |\n| `p6-dev-standalone-gateway5` | Development standalone with Gateway5 |\n| `p6-dev-standalone-no-gateway` | Development standalone without Gateway |\n\n## Multi-Tenant Mode\n\nMulti-tenant mode is designed for Itential Customer Success staff who manage capture data from multiple customer organizations. Enable it by setting `\"multi_tenant_mode\": true` in the configuration file.\n\nCustomer data is organized under `~/.atlas/customer-data/\u003corganization\u003e/` with session-based directories for each capture.\n\n```bash\n# Import a customer's capture file\nplatform-atlas customer import capture.json --organization \"Acme Corp\"\n\n# List all customer organizations\nplatform-atlas customer list\n\n# List sessions for an organization\nplatform-atlas customer sessions \"Acme Corp\"\n\n# Validate a customer session\nplatform-atlas customer validate \"Acme Corp\" 2026-q1\n\n# Generate a report for a customer session\nplatform-atlas customer report \"Acme Corp\" 2026-q1\n```\n\n## Required Permissions\n\nPlatform Atlas is designed to operate with read-only access. No write permissions are required on target systems. Sudo is not required, but if the SSH user has passwordless sudo available, Atlas will automatically use it as a fallback to read configuration files that are not readable by the SSH user directly. (e.g. `/etc/redis/redis.conf`).\n\n### SSH\n\nA read-only user with key-based authentication. Needs to read configuration files under `/opt/` and `/etc/`, and to run a limited set of commands: `hostname`, `uname`, `nproc`, `stat`, `realpath`, `cat`, `systemctl` (read-only), `sqlite3` (read-only), `python`, `pip`, `command`, `iagctl`, `printenv`, and `echo`.\n\nPlease see the separate guide entitled `SSH_SETUP_GUIDE` for full details on how to setup SSH access for all servers.\n\n### MongoDB\n\nA dedicated user created in the `admin` database with `clusterMonitor` for server diagnostics and `read` on the Platform database. Create it from mongosh:\n\n```javascript\ndb.getSiblingDB(\"admin\").createUser({\n    user: \"platformatlas\",\n    pwd: \"securepassword\",\n    roles: [\n        { role: \"clusterMonitor\", db: \"admin\" },\n        { role: \"read\", db: \"itential\" }\n    ]\n})\n```\n\nThe `clusterMonitor` role grants read-only access to `serverStatus`, `replSetGetStatus`, `dbStats`, and other diagnostic commands. The `read` role grants read access to collections in the Platform database. Neither role allows any write or destructive operations.\n\nYour MongoDB URI must include `authSource=admin` since the user is created in the `admin` database:\n\n```\nmongodb://platformatlas:securepassword@mongo-host:27017/itential?authSource=admin\n```\n\n\u003e **Note:** If your environment cannot grant `clusterMonitor`, Atlas will still work — server status and replica set metrics will be skipped, and the corresponding validation rules will show as SKIP in the report. The `read` role alone is sufficient for `dbStats` and collection-level checks.\n\n### Redis\n\nA user with the minimum required ACL permissions:\n\n```\nuser platformatlas on \u003esecurepassword allcommands -@all +info +acl +ping +role +command +config|get\n```\n\n### Platform OAuth\n\nA read-only Platform Service Account created under **Admin Essentials → Authorization → Clients** with the following permissions:\n\n```\napiread:Adapters\napiread:Applications\napiread:Health\napiread:Indexes\napiread:Server\n```\n\n## Security\n\nPlatform Atlas is built with a security-first approach for enterprise environments:\n\n- **Read-Only Operation** — All data collection is strictly read-only. No modifications are made to any target system.\n- **Credential Isolation** — Sensitive credentials (MongoDB URI, Redis URI, Platform client secret, SSH passphrase) are stored in the OS keyring or Hashicorp Vault, never in configuration files. Vault integration is read-only from Atlas; secrets are managed externally.\n- **Command Allowlisting** — SSH and local command execution is restricted to a hardcoded allowlist of safe commands. Shell metacharacters and injection patterns are blocked.\n- **Path Validation** — File reads are restricted to allowed directory prefixes with traversal detection and symlink resolution.\n- **Transport Security** — SSH host key verification with configurable policies. File size limits prevent reading excessively large files.\n- **Configuration Permissions** — Config file permissions are checked on load with warnings for overly permissive access.\n- **Data Redaction** — Session exports support automatic redaction of sensitive values.\n\n## Themes\n\nPlatform Atlas uses the **Atlas Horizon** design system with semantic color tokens for consistent visual hierarchy across both terminal UI and HTML reports.\n\nAvailable themes:\n\n| Theme | Description |\n|---|---|\n| `horizon-dark` | Cyan and purple on dark background |\n| `horizon-prism` | Teal and rose on deep indigo |\n| `horizon-core` | Warm coral and amber sunset tones (default) |\n| `horizon-light` | Light mode with teal and purple accents |\n\nSwitch themes interactively:\n\n```bash\nplatform-atlas config theme\n```\n\nOr set directly in `~/.atlas/config.json`:\n\n```json\n{\n    \"dark_mode\": true,\n    \"theme\": \"horizon-prism\"\n}\n```\n\n## Troubleshooting\n\nPlatform Atlas writes to a log file at `~/.atlas/atlas.log`. For more verbose output, enable debug logging:\n\n```bash\n# Via command-line flag\nplatform-atlas --debug session run capture\n\n# Or permanently in config.json\n{\n    \"debug\": true\n}\n```\n\n### Raw Capture Export (Authoring New Rules)\n\nWhen `session run capture` finishes, Atlas writes `01_capture.json` — a copy of the captured data **pruned** to only the dot-paths the active ruleset references (plus a few passthrough sections for the operational/architecture reports). That keeps the file small but means any path the ruleset doesn't already use is invisible — which is awkward when you're trying to author a *new* rule and need to see what's actually available under, say, `mongo.config_file.systemLog.*`.\n\nAtlas can also write an **unfiltered** companion file, `01_raw_capture.json`, containing the full reshaped capture **before** ruleset filtering. The shape is identical to `01_capture.json` — same nested keys, same dot-paths — just without the prune step, so every value the collectors returned is visible. Use it to find the exact dot-notation path you want to target, then add the new rule to your ruleset and re-run validate.\n\nTwo ways to enable the raw export (whichever you set, or both):\n\n**Per-environment (persistent):** Set `debug_export_raw_capture: true` on the environment. Use `platform-atlas env edit`, choose `Debug: Export Raw Capture`, and toggle it on. Every capture against that environment will write `01_raw_capture.json` until you turn it off.\n\n```bash\nplatform-atlas env edit production\n# → select \"Debug: Export Raw Capture\" → on\n```\n\nYou can also edit the environment file directly under `~/.atlas/environments/\u003cname\u003e.json`:\n\n```json\n{\n    \"name\": \"production\",\n    ...\n    \"debug_export_raw_capture\": true\n}\n```\n\n**Per-run (one-off):** Pass `--debug-raw-capture` to a single capture without changing the environment.\n\n```bash\nplatform-atlas session run capture --debug-raw-capture\n```\n\nThe flag takes effect for that run only and OR-combines with the env-level setting — turning the flag on never disables the env toggle, and an env toggle stays on across runs without the flag.\n\nOnce enabled, the file appears next to the regular capture:\n\n```\n~/.atlas/sessions/\u003csession\u003e/\n├── 01_capture.json         # Filtered to ruleset paths (always written)\n└── 01_raw_capture.json     # Unfiltered reshape (debug only)\n```\n\nBoth flows work identically in the WebUI — the env toggle is editable from the Environment form and the raw file is written into the session directory whenever the toggle is on. The WebUI does not have a per-run override (no CLI flag context); use the env toggle there.\n\n\u003e **Disk note:** The raw file can be several times larger than the filtered one on large deployments — it contains every nested section the collectors returned. Leave the toggle off for routine audits and only flip it on while authoring rules.\n\n### Common Issues\n\n**\"Config file not found\"** — Run `platform-atlas config init` to create the initial configuration.\n\n**\"No ruleset loaded\"** — If you created the session with v1.5+, switch to it with `platform-atlas session switch` to restore its bound ruleset and profile. For older sessions or manual control, use `platform-atlas ruleset setup` to interactively select a ruleset and profile.\n\n**\"Connection refused\" during preflight** — Verify the target host is reachable, the correct port is configured, and the SSH user has key-based access.\n\n**\"Permission denied\" on config file** — Set proper permissions: `chmod 600 ~/.atlas/config.json`.\n\n**\"Insecure keyring backend\"** — Install a supported keyring backend. On headless Linux, install `gnome-keyring` or `kwallet`, or set the `PYTHON_KEYRING_BACKEND` environment variable. After the backend is in place, run `platform-atlas config credentials` to populate it with your environment's secrets — Atlas will not auto-migrate credentials from a previous insecure backend.\n\n**\"Authentication failed\" / \"401 Unauthorized\" against Platform, MongoDB, Redis, or Gateway4** — A stored credential is wrong, expired, or rotated upstream. Run `platform-atlas config credentials` to update it; this rewrites the keyring entry for the active environment without recreating the environment file. Re-run `platform-atlas preflight` to verify.\n\n**\"No credential found for `\u003ckey\u003e`\"** — A required secret was never stored in the keyring (common after restoring `~/.atlas/` from a backup, switching machines, or initializing the encrypted backend on a headless server). Run `platform-atlas config credentials` and supply the missing value. The keyring is intentionally not part of `~/.atlas/`, so credentials never travel with the config directory.\n\n**\"Vault unreachable\" or \"Credential Backend Failed\"** - Vault is configured as the credential backend but Atlas cannot connect. Verify that Vault is running and the URL is correct. For **token** auth, check that the token hasn't expired. For **approle**, verify both `role_id` and `secret_id` are valid. For **approle_wrapped**, the wrapping token may have already been used or expired — obtain a new one and run `platform-atlas config credentials`. For **token_file**, verify that Vault Agent is running and has written a token to the configured sink path. For **token_env**, verify that `VAULT_TOKEN` is set in the environment before running Atlas. Run `platform-atlas preflight` to diagnose.\n\n**\"Missing credentials\" with Vault backend** - The required secrets are not present at the configured Vault path. Add them at the path shown in the error message (default: `secret/data/platform-atlas`) using the Vault CLI or UI.\n\n**Capture module fails but others succeed** — This is by design. Platform Atlas continues collecting from remaining modules. Use `--skip-guided` to suppress fallback prompts, or provide the missing data through guided collection. For bulk import of pre-collected files, use `--manual --import-dir \u003cdirectory\u003e`.\n\n**\"Environment not found\"** — The environment specified by `--env`, `ATLAS_ENV`, or `active_environment` in config.json doesn't exist in `~/.atlas/environments/`. Run `platform-atlas env list` to see available environments, or `platform-atlas env create` to set one up.\n\n## Directory Structure\n\n```\n~/.atlas/\n├── config.json                     # Global configuration (no secrets)\n├── settings.json                   # Active ruleset and profile pointers\n├── atlas.log                       # Application log\n├── environments/                   # Named deployment targets\n│   ├── production.json\n│   ├── staging.json\n│   └── dev.json\n├── sessions/                       # Audit sessions\n│   └── prod-audit-q1/\n│       ├── session.json            # Session metadata (bound env, ruleset, profile, org)\n│       ├── 01_capture.json         # Captured configuration data (filtered to ruleset paths)\n│       ├── 01_raw_capture.json     # Optional: unfiltered reshape — written only when\n│       │                           #   debug_export_raw_capture is on (env or --debug-raw-capture)\n│       ├── 02_validation.parquet   # Validation results\n│       ├── 03_report.html          # Compliance report\n│       ├── 04_operational.html     # Operational report (logs + pipeline metrics)\n│       └── 05_arch.html            # Architecture \u0026 Maintenance report\n├── pipelines/                      # Operational report pipeline definitions\n│   └── topworkflows.json\n└── customer-data/                  # Multi-tenant customer data\n    └── acme-corp/\n        └── 2026-q1/\n            ├── 01_capture.json\n            ├── 02_validation.parquet\n            └── 03_report.html\n```\n\n## Upgrading\n\n### From 1.6.x → 1.7\n\nAll existing sessions, environments, and captures continue to work without changes. Your installation is automatically assigned **Extended** tier on first run, which preserves the full infrastructure audit behavior from 1.6.x.\n\nIf you want to switch to Standard tier for application-only audits, run:\n\n```bash\nplatform-atlas tier set standard\n```\n\nThe optional WebUI can be installed independently — it does not affect CLI behavior.\n\n### From Pre-1.5\n\nStarting in v1.5, sessions bind an environment, ruleset, and profile at creation time. Switching sessions restores the full context automatically — no more separately managing `env switch`, `ruleset load`, and `ruleset profile set`.\n\nExisting sessions and environments continue to work without changes. Sessions created before 1.5 won't have bound metadata, but you can backfill it from capture data with `platform-atlas session repair`. Environments can be updated with `platform-atlas env edit` to add an organization name.\n\n## Support\n\nFor issues, questions, or feature requests, please contact:\n\n- **Email:** cody.rester@itential.com\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details.\n\n---\n\n**Version:** 1.7.0\n**Author:** Cody Rester\n**Last Updated:** May 2026","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitential%2Fplatform-atlas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitential%2Fplatform-atlas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitential%2Fplatform-atlas/lists"}