Capture config, validate against rulesets, report
Enterprise configuration auditing and compliance reporting for Itential Platform
Platform Atlas is a comprehensive CLI tool that captures configuration data from Itential 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.
platform-atlas tier set; SaaS is chosen per-environment at create time.platform-atlas-webui wheel) for managing sessions, running captures, streaming live job output, and browsing reports—no CLI knowledge required.platform-atlas-webui --mcp-server), that lets an AI assistant such as Claude answer questions about the sessions already in ~/.atlas—compliance summaries, top fixes across environments, score trends, regressions, and side-by-side environment comparisons. It can't capture, validate, or change anything. See Atlas MCP server.--import-dir) for importing all pre-collected files at once without interactive prompts—re-runnable to incrementally add data.session run report generates a single standalone report.html folding Compliance, Operational, and Architecture into one tabbed file, and opens it automatically in the browserconfig edit → Advanced, without touching rulesets. A disabled check shows as "Module Deactivated" in the report rather than looking like a failure. All modules default to enabled except RBAC, which stays opt-in~/.atlas/pipelines/network_policy: "disallow" in config edit blocks all outbound connections to third-party services not part of the audited environment (font CDN, adapter/ruleset version checks, webhook notifications)clusterMonitor (admin) + read on the Platform database (Extended tier only)Wheel packages for every release are available on the GitHub releases page.
Platform 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 Itential Platform environment.
# Create and activate a virtual environment
python3 -m venv atlas-venv
source atlas-venv/bin/activate
# Install the CLI (required)
pip3 install platform_atlas-<version>-py3-none-any.whl
# Install the WebUI (optional—adds the browser interface)
pip3 install platform_atlas_webui-<version>-py3-none-any.whl Verify the installation:
platform-atlas --version If the target server has no internet access, build a self-contained bundle on an internet-connected Mac or Windows workstation and transfer it to the server. The entire process takes just a few minutes.
Step 1—On the internet-connected machine
Download the Platform Atlas wheel from the GitHub release page, then run a single pip download command to pull all dependencies as pre-built Linux binaries:
# macOS / Linux
mkdir atlas-bundle
pip download ./platform_atlas-<version>-py3-none-any.whl \
--only-binary=:all: \
--python-version 3.11 \
--platform manylinux_2_28_x86_64 \
--dest atlas-bundle/ Windows: Open Command Prompt or PowerShell and run the same command on a single line (drop the backslash line continuations).
The --platform manylinux_2_28_x86_64 flag is the key—it tells pip to download RHEL 8/9-compatible Linux wheels even though your workstation is a Mac or Windows machine. All transitive dependencies are resolved and downloaded automatically. The --only-binary=:all: flag ensures you get pre-built wheels rather than source packages that would require a compiler on the server.
If you also want the optional WebUI, run a second download command in the same folder:
pip download ./platform_atlas_webui-<version>-py3-none-any.whl \
--only-binary=:all: \
--python-version 3.11 \
--platform manylinux_2_28_x86_64 \
--dest atlas-bundle/ Zip the folder when done:
zip -r atlas-bundle.zip atlas-bundle/ Windows: Right-click the
atlas-bundlefolder and choose Send to → Compressed (zipped) folder, or use 7-Zip.
Step 2—Transfer to the server
Copy atlas-bundle.zip to the target server using USB, SCP through a jump host, or whatever your air-gap transfer method is. The bundle is typically 100–200 MB (300–400 MB with the WebUI).
Step 3—On the RHEL 9 server
Python 3.11 must already be installed on the server (it is a prerequisite for Platform Atlas). Then:
unzip atlas-bundle.zip
cd atlas-bundle
# Create and activate a virtual environment
python3.11 -m venv ~/.atlas-env
source ~/.atlas-env/bin/activate
# Install Atlas and all dependencies from the local folder—no network access required
pip install --no-index --find-links . platform_atlas-*.whl
# If you also included the WebUI:
pip install --no-index --find-links . platform_atlas_webui-*.whl
# Verify
platform-atlas --version The --no-index flag disables PyPI entirely and --find-links . tells pip to resolve everything from the current directory. No network access is made during this step.
When a new version is available, use --force-reinstall and --no-compile instead of a plain pip install -U:
pip install --force-reinstall --no-compile platform_atlas-<version>-py3-none-any.whl
# If you also use the WebUI:
pip install --force-reinstall --no-compile platform_atlas_webui-<version>-py3-none-any.whl Why not just pip install -U? A plain upgrade can leave stale .pyc bytecode files from the previous version in place—especially if a module was renamed or removed between releases. On some filesystems (NFS, RHEL with coarse timestamp resolution) these stale files are not detected as out of date and can cause confusing import errors or silently run old code. --force-reinstall does a full file replacement; --no-compile skips pre-generating bytecode so Python regenerates it fresh on the first run instead.
Note on first-run speed after upgrade: Because
--no-compiledefers bytecode compilation, the very first run after upgrading will be slightly slower than usual while Python builds the cache. This is a one-time cost—every subsequent run is normal speed.
If you installed the WebUI wheel, launch it with:
platform-atlas-webui This 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.
Platform Atlas stores sensitive credentials (MongoDB, Redis, Platform OAuth, SSH passphrases, Gateway passwords) in one of three explicit backends you choose at setup—never in config files on disk. The OS Keyring is the recommended default; an encrypted local file and HashiCorp Vault are the other two. Atlas uses exactly the store you pick and never auto-switches between them.
With the OS keyring, each environment's secrets are scoped under platform-atlas/<env-name> so production credentials are completely isolated from dev/staging credentials.
| Platform | OS keyring backend used |
|---|---|
| macOS | Keychain (built-in) |
| Windows | Credential Locker (built-in) |
| Linux (desktop) | GNOME Keyring / KWallet via SecretService |
| Linux (headless) | No usable OS keyring—choose the encrypted local file store (see below) |
Reconfigure or rotate credentials at any time:
platform-atlas config credentials This 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:
keyring, file, or vault)env create flow (e.g. retrofitting a Gateway4 password onto an existing environment)You do not need to recreate the environment to update credentials.
The encrypted local file is a first-class backend you choose explicitly at setup—not an automatic fallback. Pick it on a headless Linux server with no D-Bus session, or anywhere you'd rather keep secrets off the OS keyring. Atlas stores credentials in a machine-bound file at ~/.atlas/credentials.enc. When you choose Vault, this is also where Vault's own connection settings can live if you'd rather not keep them in the keyring.
~/.atlas/.keysalt. The file is non-portable (it won't decrypt on another host or user account) and a single leaked file is useless without the salt. Files are written 0o600.config doctor, the banner, and config credentials all show when the file store is active—it's reported as a warning, never claimed to be an encrypted keyring.Switch an existing environment's backend (deliberately):
platform-atlas config credentials --use-file-store # switch this environment to the encrypted file
platform-atlas config credentials --use-keyring # switch it back to the OS keyring Switching re-enters the environment's secrets into the new store—nothing is silently copied between backends, so a credential is only ever where you put it.
Platform Atlas is generally used on a workstation PC, but it can be installed on a server. On headless Linux servers without a desktop environment, the OS keyring usually can't store secrets securely—so, as described above, you explicitly choose the encrypted local file store at setup (the wizard flags whether the keyring works on this host) and capture just works. No manual keyring configuration is required.
If you would instead prefer an encrypted OS keyring on the server (rather than the local file store or Vault), you can configure one by hand. Install the following packages:
pip3 install keyring keyrings.alt pycryptodome SecretStorage Atlas doesn't install pycryptodome itself, and keyrings.alt.file.EncryptedKeyring fails without it, so keep it in this command.
If SecretStorage fails to build, you may also need:
dnf install libsecret-devel python3-dbus Then configure keyring to use the encrypted file backend:
mkdir -p ~/.config/python_keyring
cat > ~/.config/python_keyring/keyringrc.cfg << EOF
[backend]
default-keyring=keyrings.alt.file.EncryptedKeyring
EOF You can verify the backend is active with:
python3 -c "import keyring; print(keyring.get_keyring())" This 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.
Alternative: per-shell override via environment variable
If you see the error Environment variable DBUS_SESSION_BUS_ADDRESS is unset, the keyring is trying to reach a D-Bus session bus that does not exist on a headless server. Instead of writing keyringrc.cfg, you can select a file backend directly with the PYTHON_KEYRING_BACKEND environment variable. This takes effect for the current shell—add it to ~/.bashrc to persist it:
# Encrypted file backend—prompts for a master password on first write (recommended)
export PYTHON_KEYRING_BACKEND=keyrings.alt.file.EncryptedKeyring
# Unencrypted file backend—no prompt, fastest way to unblock, but credentials
# are stored in cleartext. Lock the file down afterward:
# chmod 600 ~/.local/share/python_keyring/keyring_pass.cfg
export PYTHON_KEYRING_BACKEND=keyrings.alt.file.PlaintextKeyring Keep the same export set in the shell that runs platform-atlas config credentials and platform-atlas session run capture, so credentials are written to and read from the same backend. For fully non-interactive runs (no TTY to enter a master password), prefer PlaintextKeyring with tightened file permissions, or use the HashiCorp Vault backend below.
Platform 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 runtime but never writes to Vault—secrets are managed externally through the Vault UI, CLI, or API calls outside of Atlas.
Vault's own connection settings (URL, auth method, token or AppRole credentials, mount path) need a local home—Atlas asks where to keep them when you choose Vault, with the OS keyring recommended (stored under a vault_ prefix, off disk). The encrypted local file is the alternative when the keyring isn't usable on the host.
To configure Vault as the credential backend, run the setup wizard and select "vault" when prompted:
platform-atlas config init Or reconfigure credentials for an existing installation:
platform-atlas config credentials Atlas supports five Vault authentication methods, grouped by use case:
Standard—credentials stored in the OS keyring:
| Method | What to provide | When to use |
|---|---|---|
| Token | A static Vault token | Simple setups; token is long-lived or manually rotated |
| AppRole | role_id + static secret_id | Machine-to-machine auth; secret_id does not rotate |
Automated / rotating credentials—no long-lived secret stored in Atlas:
| Method | What to provide | When to use |
|---|---|---|
| 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 |
| 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 |
| Token (env) | (none stored) | Pipeline or orchestrator sets VAULT_TOKEN before running Atlas; Atlas reads it at runtime |
For 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.
For 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.
Secrets should be stored in Vault as key-value pairs at the configured path (default: secret/data/platform-atlas):
| Vault Key | Description |
|---|---|
platform_client_secret | Platform OAuth client secret (required) |
mongo_uri | MongoDB connection URI |
redis_uri | Redis connection URI |
ssh_key_passphrase | SSH key passphrase (if applicable) |
You can verify the backend is active with:
platform-atlas config show The credential backend type will be displayed in the configuration output. Preflight checks will verify Vault connectivity and confirm that required secrets are present.
To configure Platform Atlas for the first time, run it without any arguments:
platform-atlas If no configuration file exists, this will launch an interactive setup wizard. Setup only asks for color theme and organization name—saved to ~/.atlas/config.json. SSL verification defaults to false (change it later via config edit).
A final prompt—"Would you like to create your first environment now?"—is optional. Decline it and setup exits cleanly with a summary of what you can still do without one: config doctor, config edit, guide, and the dashboard all work fine with no environment configured. Commands that need one (session, preflight, fleet, continuous-audit, support-bundle) show a clear "no environment configured" message and exit until you create one.
Accepting it walks you straight into the terminal environment wizard, starting with the tier question (Standard, Extended, or SaaS), then credentials and topology for that tier. If you'd rather create it later, platform-atlas env create asks how you want to fill it in: right in the terminal (the same guided wizard), or in your browser (fill out a form, then finish from the CLI with env create --from-file).
You can also run the setup wizard directly at any time:
platform-atlas config init Global 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/<env-name>) or read from HashiCorp Vault if configured as the credential backend.
Global settings that apply across all environments are stored in ~/.atlas/config.json:
{
"organization_name": "Acme Corp",
"active_environment": "production",
"tier": "standard",
"verify_ssl": false,
"dark_mode": true,
"theme": "horizon-prism",
"extended_validation_checks": true,
"credential_backend": "keyring",
"debug": false
} Each environment file (~/.atlas/environments/<n>.json) contains the connection and deployment details for one target:
{
"name": "production",
"description": "Production Platform cluster - US East",
"platform_uri": "https://platform.acme.com:3443",
"platform_client_id": "6920cb7d61910148410489f9",
"credential_backend": "keyring",
"deployment": {
"mode": "standalone",
"capture_scope": "primary_only",
"nodes": [
{
"role": "all",
"host": "platform-01.acme.com",
"ssh_user": "atlas",
"ssh_port": 22
}
]
}
} When 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/<env-name>, keeping each environment's secrets isolated.
Standard and Extended environments also require an Environment type—Production, Staging, or Dev / Test. Atlas uses it to pick a matching ruleset profile automatically, and it also colors the capture banner so you can tell at a glance which kind of environment you're about to touch. It replaces the optional Banner Tint setting from earlier releases; existing environments keep their saved value. SaaS environments don't use it.
platform-atlas config show # Display current config (redacted)
platform-atlas config show --full # Display config including secrets
platform-atlas config credentials # Manage stored credentials
platform-atlas config deployment # Reconfigure deployment topology
platform-atlas config edit # Edit settings (behavior, timeouts, theme, SSL)
platform-atlas config doctor # Run a configuration health check config doctor is a one-shot diagnostic that verifies the global config, active environment, credential backend, Platform/Gateway URL reachability, active ruleset, and SSH key path in a single pass. It also reports the total on-disk size of ~/.atlas under a Runtime line, so you can see at a glance how much space sessions, captures, and reports are using. Use it after config init, after editing an environment, or any time a capture fails for an unclear reason—it surfaces every issue at once rather than letting them appear one-by-one across multiple capture runs. Exits non-zero on warnings or errors so it composes cleanly with shell scripts and CI.
Environments let you define and switch between multiple Itential Platform 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.
# List all environments (shows which is active)
platform-atlas env list
# Create a new environment (interactive wizard)
platform-atlas env create
# Create by copying an existing environment
platform-atlas env create staging --from production
# Switch the active environment
platform-atlas env switch staging
# Show details of an environment
platform-atlas env show production
# Edit an environment file in $EDITOR
platform-atlas env edit staging
# Remove an environment
platform-atlas env remove dev Use the --env flag to target a specific environment without switching the global active:
platform-atlas --env dev preflight
platform-atlas --env staging session run capture When Atlas starts, the active environment is resolved in this order:
--env CLI flag (highest priority)ATLAS_ENV environment variableactive_environment field in config.jsonconfig.json directlyIf 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.
Platform Atlas supports three deployment architectures:
all role for all-in-one nodes, or individual iap, mongo, redis, iag roles for split configurations.The capture_scope setting controls how many nodes the capture engine connects to:
Atlas operates in one of three modes:
| Standard | SaaS | Extended | |
|---|---|---|---|
| Audits | Platform application layer | Adapter and application health on Platform (read-only), plus an optional Gateway 4, Gateway 5, or both | Full Platform deployment |
| Collectors | Platform OAuth, Gateway 4 API | Platform OAuth (limited set), plus gateway SSH or the Gateway 5 Compose/Helm file source | All Standard + SSH, MongoDB, Redis, Kubernetes, Gateway5 |
| Rules | 57 | Gateway rules only—11 for Gateway 4, 25 for Gateway 5, 36 for both. No Platform (PLAT-) rules | 123 |
| SSH required | No | Gateway server only, unless you use the Gateway 5 file source | Yes |
| Platform / MongoDB / Redis | Platform only | Platform OAuth only (8 adapter and application checks). No Platform SSH, MongoDB, or Redis | Yes |
| Best for | Application-layer audits, quick checks, restricted environments | SaaS/cloud customers who can reach Platform and their gateway but not the underlying servers | Full infrastructure compliance audits |
Fresh installs default to Standard. Upgrades from 1.6.x default to Extended to preserve existing behavior. SaaS is chosen per-environment at create time (platform-atlas env create)—it is never a global default, and a SaaS environment's tier and gateway kind are fixed for its lifetime. A SaaS audit produces a single report file: the compliance report with the Architecture Overview merged in.
Starting in 3.0, a SaaS environment connects to Platform through OAuth, so a Platform URI and OAuth client are required. The gateway is optional: choose Gateway 4, Gateway 5, both, or Platform only. Atlas uses Platform in a limited, read-only way, and it runs exactly eight checks: the seven adapter checks (health data, limit errors, logger levels, states, throttling, timeouts, and versions) plus application states. It runs no PLAT- compliance rules and never connects to Platform over SSH. If you choose a gateway, Atlas connects to the gateway server over SSH; for Gateway 5 you can use the Compose/Helm file source instead.
platform-atlas tier show # Show active tier and what is enabled
platform-atlas tier set standard # Switch to Standard (non-interactive)
platform-atlas tier set extended # Switch to Extended (non-interactive)
platform-atlas tier upgrade # Guided Standard → Extended flow
platform-atlas tier upgrade --from-file <bundle> # Finish an upgrade started in the browser form
platform-atlas tier downgrade # Guided Extended → Standard flow tier upgrade walks you through the extra pieces Extended needs—deployment topology, SSH, and MongoDB/Redis connections—on your active environment, one stage at a time, in the terminal or in a browser form. The tier only switches at the very end, so backing out at any point leaves the environment unchanged in Standard Mode.
Use the --tier flag to override the tier for a single command without changing the persisted setting:
platform-atlas --tier standard session run capture Sessions 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. tier upgrade/downgrade apply to Standard ↔ Extended only—SaaS environments are created as SaaS and stay SaaS (create a new environment to change direction).
Kubernetes 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.
When creating an environment, select Kubernetes as the deployment mode. The setup wizard will prompt for:
| Field | Purpose |
|---|---|
values_yaml_path | Path to the Itential Platform Helm values.yaml |
iag5_values_yaml_path | Path to the IG5 values.yaml (optional) |
use_kubectl | Enable live kubectl collection |
kubectl_context | kubectl context name (leave blank for current context) |
kubectl_namespace | Kubernetes namespace (default: default) |
These fields are also editable after setup via platform-atlas env edit → Deployment Topology → Edit Kubernetes settings (namespace, context, values.yaml paths, kubectl binary), or the WebUI Environments form—no need to re-run the full topology wizard for a Kubernetes environment.
For the rare case of a second Platform or Gateway5 deployment living in its own namespace or cluster, an advanced, opt-in Additional namespaces option (in env create/env edit → Deployment Topology → Edit Kubernetes settings, the tier upgrade walkthrough, or the browser setup form) captures and validates each extra namespace independently, with its own pass/fail results shown in the report.
For Kubernetes environments, each data type is collected in this order, using the first source that succeeds:
printenv (if use_kubectl: true)—live environment variables from inside a running Itential Platform podMongoDB 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.
The 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 <pod> -- printenv—the live ITENTIAL_* environment variables baked into the running pod.
Group 1—Pod environment variables (ITENTIAL_* → platform.config_file.*)
| Rule | Primary path | kubectl alt_path | Pod env var |
|---|---|---|---|
| Platform Default User | platform.config.default_user_enabled.value | platform.config_file.default_user_enabled | ITENTIAL_DEFAULT_USER_ENABLED |
| Platform Core Logging Level | platform.config.log_level.value | platform.config_file.log_level | ITENTIAL_LOG_LEVEL |
| Server ID | platform.config.server_id.value | platform.config_file.server_id | ITENTIAL_SERVER_ID |
| Mongo Auth Enabled | platform.config.mongo_auth_enabled.value | platform.config_file.mongo_auth_enabled | ITENTIAL_MONGO_AUTH_ENABLED |
| Mongo TLS Enabled | platform.config.mongo_tls_enabled.value | platform.config_file.mongo_tls_enabled | ITENTIAL_MONGO_TLS_ENABLED |
| Log Max Files | platform.config.log_max_files.value | platform.config_file.log_max_files | ITENTIAL_LOG_MAX_FILES |
| Log File Max Size | platform.config.log_max_file_size.value | platform.config_file.log_max_file_size | ITENTIAL_LOG_MAX_FILE_SIZE |
| Webserver HTTPS Enabled | platform.config.webserver_https_enabled.value | platform.config_file.webserver_https_enabled | ITENTIAL_WEBSERVER_HTTPS_ENABLED |
| Webserver HTTP Enabled | platform.config.webserver_http_enabled.value | platform.config_file.webserver_http_enabled | ITENTIAL_WEBSERVER_HTTP_ENABLED |
| Webserver Timeout | platform.config.webserver_timeout.value | platform.config_file.webserver_timeout | ITENTIAL_WEBSERVER_TIMEOUT |
*Group 2—kubectl system data (`system.kubernetes.`)**
These 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 Itential Platform pod is found.
| Rule | Primary path | kubectl alt_path | Source inside pod |
|---|---|---|---|
| Platform Version | platform.health_server.version | system.kubernetes.platform_release_version | cat /opt/itential/platform/server/release_metadata.json |
| Node Version | platform.health_server.versions.node | system.kubernetes.node_version | node --version |
| 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 |
Debug logging: When
--debugis enabled (or"debug": trueinconfig.json), Atlas logs everykubectlcommand 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.
When an environment includes a Gateway 5, Atlas reads its GATEWAY_* settings from one of four sources, chosen during env create / env edit:
printenv—live environment variables from the running gateway host (default).environment: block of a local compose file; no SSH needed for containerized gateways.env / extraEnv and the Gateway 5 chart's serverSettings / applicationSettings / runnerSettings.gateway.conf over SSH—reads the Gateway 5 server config file (INI); only a server-mode file is accepted.All four feed the same gateway5.* rules, so results are identical regardless of source. File and server-config sources are validated during preflight.
Some 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.
Atlas 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.
ControlMaster can be set on any node in the topology—not just the Platform node. Each role (Platform, MongoDB, Redis, Gateway) has its own independent socket. In HA2, only the primary node of each role needs an open socket; non-primary nodes are never SSH-connected under the default primary_only capture scope.
Before running Atlas, open one master connection per role from your workstation. Each is the step that triggers MFA—complete it interactively, then Atlas takes over.
Atlas defaults to short role-based socket names stored under ~/.atlas/sockets/:
# Platform / Itential Platform node
ssh -M -S ~/.atlas/sockets/platform-01.sock \
-o ControlPersist=10m \
-o StrictHostKeyChecking=no \
-o UserKnownHostsFile=/dev/null \
-fN user@[email protected]
# MongoDB primary (Extended tier only)
ssh -M -S ~/.atlas/sockets/mongo-01.sock \
-o ControlPersist=10m \
-o StrictHostKeyChecking=no \
-o UserKnownHostsFile=/dev/null \
-fN user@[email protected]
# Redis primary (Extended tier only)
ssh -M -S ~/.atlas/sockets/redis-01.sock \
-o ControlPersist=10m \
-o StrictHostKeyChecking=no \
-o UserKnownHostsFile=/dev/null \
-fN user@[email protected] | Flag | Purpose |
|---|---|
-M -S <socket> | Create a ControlMaster socket at that path |
-o ControlPersist=10m | Keep the socket alive for 10 minutes—enough for a full capture |
-fN | Background the process (-f) and open no remote command (-N) |
user@target@psmp-gateway | CyberArk PSMP format: <user>@<target-ip-or-host>@<psmp-gateway-host> |
You will be prompted for MFA during each step. Once complete, the master sessions run silently in the background.
Check socket health at any time:
platform-atlas env sockets <env-name> This shows the status of every ControlMaster socket—open, stale (file exists but master not responding), missing, or unconfigured.
Clean up stale sockets (master timed out or was closed):
platform-atlas env sockets <env-name> --clean This removes stale socket files so you can re-open fresh master connections without the "socket exists but is not responding" error.
Let Atlas open the master connections for you:
platform-atlas env sockets <env-name> --open Atlas runs the ssh -M command for each missing or stale node sequentially—the terminal is handed over so you can complete MFA, approve a Duo push, or enter a password inline. After each node authenticates and SSH forks to the background, Atlas re-checks the socket and reports the result before moving to the next node.
CLI—during environment setup:
When the setup wizard asks how Atlas should connect to a node, select ControlMaster. You will be prompted for:
-S socket file (default auto-generated, e.g. ~/.atlas/sockets/platform-01.sock)ssh -M command (e.g. user@[email protected])You can leave the SSH destination blank to skip a node and configure it later—the wizard will warn but continue. Fill it in afterward with env edit → Deployment Topology → Edit a node.
WebUI—in the Environment form:
Under Topology → [node] connection type, select ControlMaster—CyberArk PSMP / jump host. Two additional fields appear for the socket path and SSH destination.
Editing an individual node after setup:
platform-atlas env edit <env-name>
# → Deployment Topology
# → Edit a node
# → pick the node, then change hostname / transport / socket / SSH destination This avoids re-running the full topology wizard just to fix one node.
With the master sessions open, run Atlas normally:
platform-atlas session run capture If some sockets are closed or stale when capture starts, Atlas shows a status table and offers three choices: open them automatically (Atlas runs the SSH command and hands you the terminal for MFA), show the exact copy-paste commands, or proceed anyway. Nodes without open sockets fail individually and do not abort the entire capture; re-open them and re-run with --resume to pick up where it left off.
For Extended-tier deployments where Atlas can't reach MongoDB or Redis directly—only through a bastion host you control—an advanced, opt-in setting reuses the same ControlMaster mechanism to tunnel those two protocol connections through a jumphost. You open the jumphost's own SSH session yourself (Atlas never holds jumphost credentials); Atlas then pushes a local port-forward onto that socket for whichever of Mongo/Redis you select, with a live connectivity test before anything is saved.
Configure it in env create/env edit (look for Jumphost Tunnel under Deployment Topology), the tier upgrade walkthrough, or either browser form. session run capture checks the jumphost's socket alongside your other ControlMaster nodes before capture starts, and offers to open it automatically if it isn't ready—same status table, same --resume behavior as node-level ControlMaster above.
| Symptom | Cause | Fix |
|---|---|---|
socket exists but is not responding | Stale socket file—master timed out | platform-atlas env sockets <name> --clean, then re-open the master |
filename too long / bind error | Socket path exceeds POSIX 104-byte limit | Use the default short paths under ~/.atlas/sockets/ |
SSH destination not configured for node X | Node saved without an SSH destination | env edit → Deployment Topology → Edit a node → CM SSH destination |
Socket status shows missing at capture time | Master was never opened for this session | Run the ssh -M -S … command shown by env sockets |
Platform Atlas follows a structured sequence: Preflight → Capture → Validate → Report.
Recommended: After preflight and creating a session, run the whole pipeline in one command with
platform-atlas session run all(see Run everything at once). The individualsession run capture,session run validate, andsession run reportstages documented below still work and are useful when you want to re-run a single stage, butsession run allis the preferred way to execute a full audit.
Before capturing anything, verify that all configured connections are reachable:
platform-atlas preflight This 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.
Everything 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.
platform-atlas session create prod-audit-q1 The interactive wizard prompts you to select an environment, ruleset, and profile. The first time you create a session for an environment, Atlas saves your ruleset and profile choice on that environment and doesn't ask again—change it any time with env edit. You can also specify them directly:
platform-atlas session create prod-audit-q1 --env production --ruleset p6-master-ruleset --profile p6-prod-standalone-gateway4 To switch between sessions (also restores the bound environment, ruleset, and profile):
platform-atlas session switch
platform-atlas session list
platform-atlas session show prod-audit-q1 To edit session bindings before capture begins:
platform-atlas session edit 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, andruleset profile setcommands still work for ad-hoc use, but the session creation wizard is the recommended workflow.
The capture engine connects to your targets and collects configuration data from all enabled modules:
platform-atlas session run capture You 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.
The capture order is always: Preflight → Automated Capture → Manual Prompts → JSON Integrity Check → Customer Summary.
To capture only specific modules:
platform-atlas session run capture --modules system mongo redis To use fully manual collection (for air-gapped or restricted environments):
platform-atlas session run capture --manual If you have pre-collected data files in a directory, you can batch-import them all at once instead of going through the interactive prompts:
platform-atlas session run capture --manual --import-dir ~/atlas-capture/ Atlas 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.
Validation 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.
platform-atlas session run validate Results are stored as 02_validation.json in the session directory. The file holds every rule result and the session's validation metadata together, so Atlas loads it in a single read. Sessions validated before 3.0 have a 02_validation.parquet file instead; see Upgrading from 2.x to 3.0.
Severity levels are critical, warning, and info.
Atlas reports two scores for each validated session:
Both scores exclude skipped rules from the calculation. The dashboard and fleet status fall back to the unweighted pass rate for any session validated before the weighted score existed.
Generate a professional HTML report from the validation results:
platform-atlas session run report Reports 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.
To generate in other formats:
platform-atlas session run report --format csv
platform-atlas session run report --format json session run report generates a single standalone report.html with three pages, switched from a persistent top bar:
| Page | Contents |
|---|---|
| Compliance | Overall score, category breakdown, rule results, extended validation findings |
| Operational | Platform/webserver/MongoDB log analysis and aggregation pipeline results |
| Architecture | Adapter states, Redis ACL, index status, Gateway paths, and architecture overview, including a deployment topology diagram |
The report opens automatically in your browser. A SaaS audit merges the Architecture Overview into the Compliance page instead of showing it as a separate page.
The topology diagram is built on a best-effort basis from your architecture form answers, with real hostnames and IP addresses filled in from the environment where Atlas has them. Sections you haven't answered show as a dashed placeholder, and a report with no architecture data still renders. The section-by-section detail opens in a modal instead of always taking up the page.
Architecture form auto-detect (Extended tier)
platform-atlas env architecture offers an optional step that pre-fills what Atlas can detect from your environment—server specs, operating system, container/VM/Kubernetes signals, SELinux mode, FIPS, MTU, monitoring/log/vulnerability-scanner agents, and instance counts, datacenter placement, and topology already in your environment configuration. The form also suggests skipping the Gateway4, Gateway5, and Kubernetes sections when your topology confirms the environment doesn't have them. Atlas never overwrites an answer you've entered or a suggested skip you've unchecked, and reopening the form picks up your previous answers. Anything Atlas can't detect stays blank for you to fill in.
MongoDB Aggregation Pipelines
After 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.
You can extend the pipeline output by adding your own pipeline JSON files to ~/.atlas/pipelines/—they are discovered and executed automatically.
This is the recommended way to run an audit. To execute the full capture → validate → report pipeline in one command:
platform-atlas session run all session run all runs capture, validate, and report in the correct order and opens the report in your browser when it finishes. Reach for the individual stage commands (session run capture, session run validate, session run report) only when you need to re-run or tweak a single stage—for example, re-validating after editing the ruleset, or regenerating the report in another format.
Compare two sessions to see what changed between audits:
platform-atlas session diff baseline-q4 latest-q1 The diff report classifies each rule as Fixed, Regressed, Unchanged, New, Removed, Changed, or Skipped.
Pin a validated session as an environment's baseline when you want a fixed reference point—for example, the audit you signed off on after remediation. Atlas copies the session's validation results, so the baseline survives even if you later delete or overwrite the source session. Each environment has at most one baseline, and the session must belong to that environment.
platform-atlas env baseline set prod-audit-q1 # pin a session (interactive if you omit the name)
platform-atlas env baseline show # show the pinned baseline
platform-atlas env baseline clear # remove it Then compare any session against its environment's baseline by passing a single session name:
platform-atlas session diff --use-baseline prod-audit-q2 env baseline set overwrites an existing baseline for that environment. Add --env <name> to any env baseline action to target an environment other than the active one.
In the WebUI, open the environment's page under Environments and use the Validation baseline card to pin, change, or clear the baseline. The Diff page then shows a Compare against baseline panel for the active environment.
| Command | Description |
|---|---|
session create <n> | Create a new session (binds environment, ruleset, and profile) |
session create <n> --env --ruleset --profile | Create with explicit bindings (skips prompts) |
session list | List all sessions with environment, org, ruleset, and status |
session show [name] | Show session details and bindings |
session active [name] | Show or set the active session (restores full context) |
session switch [name] | Switch sessions (alias for active) |
session edit [name] | Edit session bindings (only before capture) |
session run <stage> | Run a workflow stage (capture, validate, report, all) |
session run capture --manual | Interactive guided collection for air-gapped environments |
session run capture --manual --import-dir <dir> | Batch import capture files from a directory |
session run report | Generate report.html (compliance, operational, architecture as pages in one file) |
session export [name] | Package the report + JSON + metadata into a delivery archive (ATLAS-<org>-<session>-<date>); --include-debug adds capture/logs |
session delete <n> | Permanently remove a session |
session diff <baseline> <latest> | Compare two sessions |
session diff --use-baseline [name] | Compare one session against its environment's pinned baseline |
session prune | Delete sessions by age, count, status, or environment. Dry run by default; pass --no-dry-run to delete |
session prune --legacy-files | Delete orphaned pre-3.0 02_validation.parquet files instead of whole sessions |
session repair [name] | Backfill missing metadata on pre-1.5 sessions |
| Command | Description |
|---|---|
ruleset setup | Interactive ruleset and profile selection (recommended) |
ruleset list | List available rulesets |
ruleset load <id> | Load and activate a ruleset |
ruleset info [id] | Show ruleset details |
ruleset active | Show active ruleset |
ruleset clear | Deactivate current ruleset |
ruleset rules [id] | Display all rules in a ruleset |
ruleset update | Fetch and apply SHA-256-verified ruleset updates from the manifest |
ruleset skip-rule <n> --reason | Suppress a rule in the active environment (shown as Suppressed; reason required) |
ruleset unskip-rule <n> | Remove a per-environment rule suppression |
ruleset profile list | List available profiles |
ruleset profile set <id> | Set a profile overlay |
ruleset profile active | Show active profile |
ruleset profile clear | Clear active profile |
| Command | Description |
|---|---|
config init | Run the interactive setup wizard |
config show | Display current configuration (redacted) |
config edit | Tune individual settings—organization name, behavior, timeouts, SSL verification, color theme, and (under Advanced) which Additional Validation Modules run—without hand-editing config.json |
config credentials | Add, rotate, or switch the backend for stored credentials |
config deployment | Reconfigure deployment topology |
config doctor | Run a one-shot configuration health check; also flags orphaned pre-3.0 02_validation.parquet files and the disk space you'd reclaim |
config architecture | Record/update infrastructure architecture info (alias of env architecture) |
| Command | Description |
|---|---|
env list | List all environments with description, platform URI, mode, backend, and active status (⚠ incomplete shown for partial setups) |
env create [name] | Create a new environment (interactive wizard; saves a draft early so Ctrl-C doesn't lose your work) |
env create [name] --from <env> | Copy from an existing environment |
env switch [name] | Switch environment and offer to switch to a bound session |
env show [name] | Show environment details |
env edit [name] | Edit environment settings; Deployment Topology opens a sub-menu: edit a node (or edit Kubernetes settings, for a Kubernetes environment), change capture scope, or replace topology |
env architecture [name] | Record/update architecture info for the report (browser or CLI form; optional auto-detect on Extended) |
env baseline set [session] | Pin a session's validation results as the environment's baseline |
env baseline show | Show the environment's pinned baseline |
env baseline clear | Remove the environment's pinned baseline |
env sockets [name] | Show ControlMaster socket health (open / stale / missing / unconfigured) |
env sockets [name] --clean | Remove stale socket files so fresh master connections can be opened |
env sockets [name] --open | Open master connections for all missing/stale nodes (Atlas runs SSH, you provide credentials inline) |
env remove <n> | Delete an environment |
| Command | Description |
|---|---|
tier show | Show the active tier and what is enabled |
tier set <tier> | Set the global tier (standard or extended) |
tier upgrade | Guided Standard → Extended upgrade flow |
tier downgrade | Guided Extended → Standard downgrade flow |
| Command | Description |
|---|---|
preflight | Run connectivity checks against all configured services |
support-bundle | Collect a diagnostic ZIP (health endpoints, redacted config, Extended logs) for a support ticket |
continuous-audit | Schedule recurring audits with alerting and run history |
fleet | Multi-environment health summary (pass rate, drift, continuous-audit state) |
guide | View the built-in help guide |
--version | Display version |
--debug | Enable debug mode with verbose logging |
--env <name> | Use a specific environment for this command |
--tier <tier> | Override the active tier for this command only |
A 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.
Platform Atlas ships with the Platform 6 Master Ruleset (p6-master-ruleset) containing 123 rules across six categories:
| Category | Rules | Rule ID prefix | Coverage |
|---|---|---|---|
| Platform | 50 | PLAT- | Application settings, adapters, services, properties |
| Gateway5 | 25 | IG- | Gateway 5 configuration, health, version checks |
| Redis | 16 | RDS- | Server config, memory, persistence, replication, ACLs |
| Kubernetes | 15 | KBS- | Probes, resource requests/limits, HPA, restart counts |
| Gateway4 | 11 | IG- | Venv packages, sync config, database settings |
| MongoDB | 6 | MDB- | Server status, version, replication, connection settings |
Severity breakdown: 29 critical, 71 warning, 23 info.
Gateway rule IDs use the IG- prefix (IG-001 through IG-011 for Gateway 4 and IG-012 through IG-036 for Gateway 5). Releases before 3.0 used IAG-. If you keep profile overrides or continuous-audit watchlists that reference the old IDs, update them to the IG- form.
A ruleset can declare the minimum Atlas version it needs (min_atlas_version in its metadata). Atlas refuses to activate a ruleset built for a newer release and tells you to upgrade, instead of silently misapplying it. The bundled master ruleset requires platform-atlas 3.0.0 or later.
Profiles are lightweight overlays that enable or disable specific rules from the master ruleset. This avoids maintaining separate ruleset copies for each environment type.
Available profiles for Platform 6 follow the pattern p6-<environment>-<topology>-<gateway>:
| Profile | Description |
|---|---|
p6-prod-standalone-gateway4 | Production standalone with Gateway4 |
p6-prod-standalone-gateway5 | Production standalone with Gateway5 |
p6-prod-standalone-gw4-gw5 | Production standalone with both Gateway4 and Gateway5 |
p6-prod-standalone-no-gateway | Production standalone without Gateway |
p6-prod-ha2-gateway4 | Production HA2 with Gateway4 |
p6-prod-ha2-gateway5 | Production HA2 with Gateway5 |
p6-prod-ha2-gw4-gw5 | Production HA2 with both Gateway4 and Gateway5 |
p6-prod-ha2-no-gateway | Production HA2 without Gateway |
p6-prod-kubernetes-gateway4 | Production Kubernetes with Gateway4 |
p6-prod-kubernetes-gateway5 | Production Kubernetes with Gateway5 |
p6-prod-kubernetes-gw4-gw5 | Production Kubernetes with both Gateway4 and Gateway5 |
p6-prod-kubernetes-no-gateway | Production Kubernetes without Gateway |
p6-dev-standalone-gateway4 | Development standalone with Gateway4 |
p6-dev-standalone-gateway5 | Development standalone with Gateway5 |
p6-dev-standalone-gw4-gw5 | Development standalone with both Gateway4 and Gateway5 |
p6-dev-standalone-no-gateway | Development standalone without Gateway |
Three more profiles—saas-gateway4, saas-gateway5, and saas-gw4-gw5—are listed only under the SaaS tier, and the SaaS tier lists only those. Each keeps only the IG- rules for its gateway kind enabled.
Platform 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).
A 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.
Please see the separate guide entitled SSH_SETUP_GUIDE for full details on how to set up SSH access for all servers.
A dedicated user created in the admin database with clusterMonitor for server diagnostics and read on the Platform database. Create it from mongosh:
db.getSiblingDB("admin").createUser({
user: "platformatlas",
pwd: "securepassword",
roles: [
{ role: "clusterMonitor", db: "admin" },
{ role: "read", db: "itential" }
]
}) The 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.
Your MongoDB URI must include authSource=admin since the user is created in the admin database:
mongodb://platformatlas:securepassword@mongo-host:27017/itential?authSource=admin 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. Thereadrole alone is sufficient fordbStatsand collection-level checks.
Atlas reads the MongoDB log file for operational analysis. MongoDB logs are typically owned by the mongod user with 0600 permissions, so the SSH user needs explicit read access. Two options:
Option A—Filesystem ACL (recommended): Grants access without touching the existing ownership or permissions. The default ACL on the directory ensures new files created by logrotate inherit it automatically.
setfacl -m u:<ssh_user>:rx /var/log/mongodb/
setfacl -d -m u:<ssh_user>:r /var/log/mongodb/
setfacl -m u:<ssh_user>:r /var/log/mongodb/mongod.log Option B—Logrotate + group membership: Add the SSH user to the mongod group and configure logrotate to create files as group-readable so the permission survives rotation.
usermod -aG mongod <ssh_user>
chmod 640 /var/log/mongodb/mongod.log Then in /etc/logrotate.d/mongodb, change create 0600 mongod mongod to create 0640 mongod mongod.
If log access isn't granted, Atlas will still complete the capture—the log analysis section of the operational report will be empty.
A user with the minimum required ACL permissions:
user platformatlas on >securepassword allcommands -@all +info +acl +ping +role +command +config|get env create/env edit offer an independent Enable TLS toggle for each of MongoDB and Redis, so a deployment can require TLS on one and not the other. When enabled, Atlas transparently upgrades the stored connection URI at connect time—appending tls=true&tlsInsecure=true for MongoDB, or switching to the rediss:// scheme with certificate verification disabled for Redis. This encrypts the connection in transit but does not verify the server's certificate, since these audits overwhelmingly target self-signed certificates; custom CA files and mutual TLS aren't supported yet.
A read-only Platform Service Account created under Admin Essentials → Authorization → Clients with the following permissions:
apiread:Adapters
apiread:Applications
apiread:Health
apiread:Indexes
apiread:Server Platform Atlas is built with a security-first approach for enterprise environments:
Platform Atlas uses the Atlas Horizon design system with semantic color tokens for consistent visual hierarchy across both terminal UI and HTML reports.
Available themes:
| Theme | Description |
|---|---|
horizon-atlas | Bioluminescent teal and ocean blue on dark background |
horizon-dark | Cyan and purple on dark background |
horizon-prism | Teal and rose on deep indigo |
horizon-core | Brass and navy, matching report.html's paper-and-ink palette (default) |
horizon-light | Light mode with teal and purple accents |
horizon-contrast | WCAG AAA (7:1) verified high-contrast theme — pure black background, maximum-contrast text and status colors |
Switch themes interactively via config edit (select Theme under the Appearance section):
platform-atlas config edit Or set directly in ~/.atlas/config.json:
{
"dark_mode": true,
"theme": "horizon-prism"
} Starting in 3.0, Atlas can act as a read-only tool for an AI assistant. An MCP (Model Context Protocol) client—for example, Claude or a Gateway 5 FlowAI agent—can ask questions about the sessions already stored in ~/.atlas without re-running a capture and without being able to change anything. Example questions include:
The server process ships and runs in the WebUI package. This platform-atlas package provides the cross-environment query engine behind it, so the CLI, WebUI, and MCP server all answer from the same code. Install the WebUI wheel to use it:
platform-atlas-webui --mcp-server # start the MCP server (default port 8766)
platform-atlas-webui print-mcp-token # print the bearer token your MCP client needs
platform-atlas-webui --mcp-server --reset-mcp-token # rotate the token The MCP server is a separate mode and process from the browser UI, with its own port, bearer token, and start/stop/status controls, so the two can run side by side. Every tool is read-only, access requires the bearer token, Atlas strips captured credentials from every response, and each tool call is written to an audit log at ~/.atlas/mcp-audit.log.
For daemon and systemd setup, TLS options, and registering the server with Gateway 5, see the platform-atlas-webui README. For example prompts for each tool, see GUIDES/MCP_TOOL_PROMPTS_REFERENCE.md.
Platform Atlas writes to a log file at ~/.atlas/atlas.log. For more verbose output, enable debug logging:
# Via command-line flag
platform-atlas --debug session run capture
# Or permanently in config.json
{
"debug": true
} When 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.*.
Atlas 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.
Two ways to enable the raw export (whichever you set, or both):
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.
platform-atlas env edit production
# → select "Debug: Export Raw Capture" → on You can also edit the environment file directly under ~/.atlas/environments/<name>.json:
{
"name": "production",
...
"debug_export_raw_capture": true
} Per-run (one-off): Pass --debug-raw-capture to a single capture without changing the environment.
platform-atlas session run capture --debug-raw-capture The 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.
Once enabled, the file appears next to the regular capture:
~/.atlas/sessions/<session>/
├── 01_capture.json # Filtered to ruleset paths (always written)
└── 01_raw_capture.json # Unfiltered reshape (debug only) Both 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.
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.
"Config file not found"—Run platform-atlas config init to create the initial configuration.
"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.
"Connection refused" during preflight—Verify the target host is reachable, the correct port is configured, and the SSH user has key-based access.
"Permission denied" on config file—Set proper permissions: chmod 600 ~/.atlas/config.json.
"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.
"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.
"No credential found for <key>"—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.
"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.
"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.
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 <directory>.
"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.
~/.atlas/
├── config.json # Global configuration (no secrets)
├── settings.json # Active ruleset and profile pointers
├── atlas.log # Application log
├── environments/ # Named deployment targets
│ ├── production.json
│ ├── staging.json
│ └── dev.json
├── sessions/ # Audit sessions
│ └── prod-audit-q1/
│ ├── session.json # Session metadata (bound env, ruleset, profile, org)
│ ├── 01_capture.json # Captured configuration data (filtered to ruleset paths)
│ ├── 01_raw_capture.json # Optional: unfiltered reshape—written only when
│ │ # debug_export_raw_capture is on (env or --debug-raw-capture)
│ ├── 02_validation.json # Validation results and metadata
│ └── report.html # Compliance, Operational, and Architecture pages
└── pipelines/ # Operational report pipeline definitions
└── topworkflows.json Atlas 3.0 changes how validation results are stored, renames gateway rule IDs, and removes 2023.x support. Existing environments and captures keep working. Check these items after you upgrade:
02_validation.json. Older sessions still hold 02_validation.parquet, which Atlas 3.0 never reads. Run platform-atlas session run validate and then platform-atlas session run report on each session you still need. The WebUI shows the same instruction when you open a pre-3.0 report.platform-atlas config doctor to see any orphaned 02_validation.parquet files and the disk space you'd reclaim. Then run platform-atlas session prune --legacy-files to preview the deletion, and add --no-dry-run to delete the files. If a session was validated but never reported, its parquet file is the only record of that run, so Atlas asks for an extra confirmation before deleting it.IAG-XXX to IG-XXX. Update any profile overrides or continuous-audit watchlists that use the old IDs.env edit to add the Platform URI and OAuth client.critical, and the headline score is now severity-weighted. A session's score can change even when nothing in your deployment did. The unweighted pass rate is still shown next to it.legacy_profile environment field are gone.pycryptodome yourself.customer command have been removed—use named environments (one per customer) instead.All existing sessions, environments, and captures continue to work.
All 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.
If you want to switch to Standard tier for application-only audits, run:
platform-atlas tier set standard The optional WebUI can be installed independently—it does not affect CLI behavior.
Starting 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.
Existing 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.
For issues, questions, or feature requests, please refer to the official Itential support channels:
This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.
Version: 3.0.0 Author: Cody Rester Last Updated: August 2026