Files
elysium/AGENTS.md
T
tomas.kracmar e270b9ab21 feat(khdb): KhdbBackupCount setting, default 1; move the old file aside instead of copying
A full-size khdb.txt is tens of GB, so five backups filled the disk and each copy took minutes.
The previous file is now renamed to khdb.txt.bak-<time> (instant on one volume) and only the newest
KhdbBackupCount are kept (0 = none). A non-numeric or negative value is rejected.
2026-11-06 08:07:46 +01:00

11 KiB

Elysium — Agent Context

This file is written for AI coding agents. The project language is English; all code comments, documentation, and settings are in English.

Project Overview

Elysium is a Windows-focused Active Directory weak-password assessment toolkit. It is implemented entirely in PowerShell (with one Python decryption helper) and is designed to be run from a dedicated, trusted Windows host by an operator with replication-equivalent rights on the target AD domain.

The tool performs three core workflows:

  1. Update Known-Hashes Database (KHDB) — Download an incremental, sharded hash database from remote storage (Azure Blob or S3-compatible).
  2. Test Weak AD Passwords — Use DSInternals to replicate account data and test passwords against the local KHDB, producing timestamped text reports.
  3. Extract and Send Current Hashes — Pull NTLM hashes (without usernames) from live AD, compress, encrypt, and upload them back to the tool provider to improve the KHDB. This step is optional.
  4. Update Lithnet Password Protection Store — Populate a local Lithnet Password Protection store with compromised hashes, plaintext passwords, and banned words.

Technology Stack

  • Runtime: Windows PowerShell 5.1 or PowerShell 7 (pwsh).
  • Required PowerShell modules: DSInternals, ActiveDirectory (RSAT).
  • Optional PowerShell modules: LithnetPasswordProtection. Storage access needs no Az/AWS modules (built-in HttpClient).
  • Python 3: tools/decrypt.py requires pycryptodome for decrypting uploaded payload files.
  • Network: TLS 1.2+ enforced; native S3 SigV4 signing implemented in pure PowerShell/.NET (no AWS Tools required).

Project Structure

Elysium.ps1                    # Main menu / orchestrator script
ElysiumSettings.txt            # Live configuration (key=value format, # comments)
ElysiumSettings.txt.sample     # Documented template for operators

src/Elysium/Elysium.psd1       # Module manifest; ModuleVersion is the single source of the project version
src/Elysium/Elysium.psm1       # Root module: dot-sources Private/ and Public/
src/Elysium/Private/           # Helpers: Relaunch, Settings, Storage (Azure/S3/SigV4), Khdb, Crypto (ELY2), AdPreflight, PasswordQuality, Transcript
src/Elysium/Public/            # Exported cmdlets (root scripts are being converted into these)

Update-KHDB.ps1                # Wrapper: relaunch under pwsh, then call Update-ElysiumKhdb (src/Elysium/Public)
Test-WeakADPasswords.ps1       # Wrapper: relaunch under powershell.exe, then call Test-ElysiumPasswordQuality
Extract-NTHashes.ps1           # Wrapper: relaunch under powershell.exe, then call Send-ElysiumHashExport
Update-LithnetStore.ps1        # Wrapper: relaunch under pwsh, then call Update-ElysiumLithnetStore
Uninstall.ps1                  # Self-removal script
tools/Prepare-KHDBStorage.ps1  # Provider only - standalone KHDB package builder: shards + manifest (no upload)
tools/decrypt.py               # Provider only - Python 3 decryptor for .enc payloads (ELY2, ELY1, legacy)
tests/test_decrypt.py          # ELY2 round trip: PowerShell encryptor -> decrypt.py

khdb.txt                       # Local merged KHDB file (generated by Update-KHDB.ps1)
Reports/                       # Generated reports and transcript logs

Configuration Format

ElysiumSettings.txt uses a simple Key=value format. Lines starting with # are comments. Values are not quoted by default; if quotes are used they are stripped by some parsers.

Key sections:

  • StorageProvider — Azure or S3
  • Azure: storageAccountName, containerName, sasToken
  • S3: s3EndpointUrl, s3Region, s3BucketName, s3AccessKeyId, s3SecretAccessKey, s3ForcePathStyle
  • KHDB layout: KhdbManifestPath, KhdbShardPrefix, KhdbLocalShardDir, KhdbBackupCount
  • App: InstallationPath, ReportPathBase, WeakPasswordsDatabase, CheckOnlyEnabledUsers
  • Lithnet: LithnetStorePath, LithnetSyncHibp, LithnetHashSources, LithnetPlaintextSources, LithnetBannedWordSources
  • Telemetry (optional): UsageBeaconUrl, UsageBeaconMethod, UsageBeaconInstanceId, UsageBeaconTimeoutSeconds
  • Domains: Domain1Name, Domain1DC, Domain2Name, Domain2DC, ...

PowerShell Edition Handling

  • The module runs on Windows PowerShell 5.1 and PowerShell 7. Nothing needs pwsh: concurrency uses Invoke-InModuleRunspace, which works on both.
  • The AD wrappers (Test-WeakADPasswords.ps1, Extract-NTHashes.ps1) dot-source src/Elysium/Private/Relaunch.ps1 and call Restart-WithWindowsPowerShellIfAvailable before importing the module, because DSInternals and ActiveDirectory often need the Desktop edition. Keep that call at the top of those two wrappers.
  • Elysium.ps1 (the menu) checks $PSVersionTable.PSEdition and starts options 2 and 3 under powershell.exe when it runs in pwsh.
  • tools/Prepare-KHDBStorage.ps1 is standalone and runs on any OS with pwsh (the provider runs it on macOS).

Code Style Guidelines

  • Strict mode and error handling are mandatory at the top of every script:
    $ErrorActionPreference = 'Stop'
    Set-StrictMode -Version Latest
    
  • Every cmdlet starts a transcript with Start-ElysiumTranscript (into Reports/logs/; Uninstall.ps1 uses %TEMP%) and stops it in a finally block.
  • Functions use Verb-Noun naming. Private helpers are also Verb-Noun.
  • Settings parsing is done manually via Get-Content and string splitting on =, not ConvertFrom-StringData.
  • Paths are resolved relative to $PSScriptRoot whenever possible.
  • Large file operations use StreamReader / StreamWriter with explicit UTF8Encoding($false) (no BOM) and large buffers (1 MiB preferred).
  • The KHDB merge and validation are compiled (src/Elysium/Private/KhdbMerge.ps1). Do not reintroduce per-line PowerShell loops over the KHDB: a full file is hundreds of millions of lines and that took hours on 5.1.
  • All storage transfers go through src/Elysium/Private/Storage.ps1 (Get-StorageConfig, Invoke-StorageDownload, Invoke-StorageUpload). Concurrency uses Invoke-InModuleRunspace (a runspace pool that imports the module), which works on 5.1 and 7 - do not use ForEach-Object -Parallel or inject function text.

Build / Run Commands

There is no package manager or build system. The tool is run directly:

# Main menu
.\Elysium.ps1

# Direct invocation (respects auto-relaunch behavior)
.\Update-KHDB.ps1
.\Update-KHDB.ps1 -MaxParallelTransfers 8
.\Test-WeakADPasswords.ps1
.\Extract-NTHashes.ps1
.\Update-LithnetStore.ps1
.\tools\Prepare-KHDBStorage.ps1 -SourcePath .\khdb.txt -OutputRoot .\publish   # build only; upload with aws s3 / rclone / azcopy (README)
.\Uninstall.ps1

No CI pipeline exists. Two automated checks, both runnable on any OS with pwsh:

  • Invoke-Pester ./tests (Pester 5): module helpers - settings parsing, storage URIs, SigV4 signatures checked against values generated by botocore, KHDB manifest/merge validation - storage transfers (retry policy, upload digests, error surfacing) and an end-to-end Update-ElysiumKhdb incremental sync against tests/FakeStorage.ps1 (an S3-style HttpListener store), Update-ElysiumLithnetStore against stubbed Lithnet cmdlets, the pure password-quality helpers (domain list, KHDB normalization for DSInternals), and a publish -> update round trip that runs tools/Prepare-KHDBStorage.ps1 and rebuilds its package with Update-ElysiumKhdb. The AD/DSInternals code paths themselves need a Windows host and a domain. Run after touching anything in src/Elysium/.
  • python3 tests/test_decrypt.py (needs pwsh on PATH and pycryptodome): encrypts with the real Protect-FileWithAES (src/Elysium/Private/Crypto.ps1) and decrypts with tools/decrypt.py. Run it after touching either side of the export format.

Testing & Validation

  • KHDB validation: Validate-KHDBFile in src/Elysium/Private/Khdb.ps1 checks 32-hex format, sorting, and duplicates.
  • DSInternals compatibility: Resolve-DSInternalsWeakHashFile in src/Elysium/Private/PasswordQuality.ps1 normalizes legacy HASH:count lines into a temporary hash-only file.
  • Upload integrity: each upload is one PUT carrying a digest the storage service verifies (Azure Content-MD5, S3 SigV4-signed SHA-256); a mismatch is rejected server-side, so nothing is read back.
  • Credential pre-check: Test-WeakADPasswords.ps1 validates credentials against the chosen DC with Get-ADDomain and checks the three replication extended rights before attempting DCSync.

Security Considerations

  • The operator passphrase is stored DPAPI-protected (ConvertFrom-SecureString) in the user-level environment variable ELYSIUM_PASSPHRASE, and decrypted only in memory right before use. Do not log or serialize the plaintext.
  • Test-WeakADPasswords.ps1 refuses to run when Windows FIPS policy is enabled (HKLM:\SYSTEM\CurrentControlSet\Control\Lsa\FipsAlgorithmPolicy\Enabled = 1) because DSInternals operations may fail or be limited.
  • The extract-and-send workflow uploads hashes only (no usernames). Encryption format ELY2: PBKDF2 (SHA-256, 100k iterations, random 16-byte salt, UTF-8 passphrase) yields 64 bytes - the first 32 are the AES-256-CBC key, the next 32 the HMAC-SHA256 key. Layout: ELY2 | salt | iv | ciphertext | HMAC(magic..ciphertext). Any change must keep decrypt.py in sync (see tests/test_decrypt.py).
  • S3 requests are signed with native SigV4 via System.Net.Http.HttpClient so no AWS credentials file or third-party module is required. Client credentials can be narrow: read-only on the KHDB paths, write-only on the upload location.
  • Reports contain sensitive AD data. They are written to Reports/ under the script root by default.
  • All network operations enforce TLS 1.2+ ([System.Net.ServicePointManager]::SecurityProtocol).

Notes for Agents

  • Do not introduce new package-manager files (e.g., package.json, pyproject.toml, Cargo.toml). This project is intentionally dependency-light and script-driven.
  • When adding new settings, keep the key=value flat format and update both ElysiumSettings.txt.sample and any parser that reads the file.
  • New functionality goes into the module: a cmdlet in src/Elysium/Public/ (added to FunctionsToExport in the manifest), helpers in src/Elysium/Private/. Add a thin root wrapper (banner, strict mode, Import-Module, call) only if operators run it directly or from the menu. Module code must not call exit (it would end the caller's session); use return or throw.
  • The version lives only in src/Elysium/Elysium.psd1 (ModuleVersion); code reads it as $ElysiumVersion. Do not add version numbers to file banners.
  • The .gitignore excludes khdb.txt, ElysiumSettings.txt, Reports/, khdb-shards/, and khdb-manifest.json. Exception: khdb.txt has been tracked since the first commit, so the ignore rule does not apply to it. Do not git rm it casually - client clones have a locally modified khdb.txt, and an upstream deletion makes their git pull fail.