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.
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:
- Update Known-Hashes Database (KHDB) — Download an incremental, sharded hash database from remote storage (Azure Blob or S3-compatible).
- Test Weak AD Passwords — Use DSInternals to replicate account data and test passwords against the local KHDB, producing timestamped text reports.
- 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.
- 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.pyrequirespycryptodomefor 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—AzureorS3- 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-sourcesrc/Elysium/Private/Relaunch.ps1and callRestart-WithWindowsPowerShellIfAvailablebefore importing the module, becauseDSInternalsandActiveDirectoryoften need the Desktop edition. Keep that call at the top of those two wrappers. Elysium.ps1(the menu) checks$PSVersionTable.PSEditionand starts options 2 and 3 underpowershell.exewhen it runs in pwsh.tools/Prepare-KHDBStorage.ps1is 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(intoReports/logs/;Uninstall.ps1uses%TEMP%) and stops it in afinallyblock. - Functions use
Verb-Nounnaming. Private helpers are alsoVerb-Noun. - Settings parsing is done manually via
Get-Contentand string splitting on=, notConvertFrom-StringData. - Paths are resolved relative to
$PSScriptRootwhenever possible. - Large file operations use
StreamReader/StreamWriterwith explicitUTF8Encoding($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 usesInvoke-InModuleRunspace(a runspace pool that imports the module), which works on 5.1 and 7 - do not useForEach-Object -Parallelor 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-endUpdate-ElysiumKhdbincremental sync againsttests/FakeStorage.ps1(an S3-style HttpListener store),Update-ElysiumLithnetStoreagainst stubbed Lithnet cmdlets, the pure password-quality helpers (domain list, KHDB normalization for DSInternals), and a publish -> update round trip that runstools/Prepare-KHDBStorage.ps1and rebuilds its package withUpdate-ElysiumKhdb. The AD/DSInternals code paths themselves need a Windows host and a domain. Run after touching anything insrc/Elysium/.python3 tests/test_decrypt.py(needspwshon PATH andpycryptodome): encrypts with the realProtect-FileWithAES(src/Elysium/Private/Crypto.ps1) and decrypts withtools/decrypt.py. Run it after touching either side of the export format.
Testing & Validation
- KHDB validation:
Validate-KHDBFileinsrc/Elysium/Private/Khdb.ps1checks 32-hex format, sorting, and duplicates. - DSInternals compatibility:
Resolve-DSInternalsWeakHashFileinsrc/Elysium/Private/PasswordQuality.ps1normalizes legacyHASH:countlines 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.ps1validates credentials against the chosen DC withGet-ADDomainand 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 variableELYSIUM_PASSPHRASE, and decrypted only in memory right before use. Do not log or serialize the plaintext. Test-WeakADPasswords.ps1refuses 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 keepdecrypt.pyin sync (seetests/test_decrypt.py). - S3 requests are signed with native SigV4 via
System.Net.Http.HttpClientso 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=valueflat format and update bothElysiumSettings.txt.sampleand any parser that reads the file. - New functionality goes into the module: a cmdlet in
src/Elysium/Public/(added toFunctionsToExportin the manifest), helpers insrc/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 callexit(it would end the caller's session); usereturnorthrow. - The version lives only in
src/Elysium/Elysium.psd1(ModuleVersion); code reads it as$ElysiumVersion. Do not add version numbers to file banners. - The
.gitignoreexcludeskhdb.txt,ElysiumSettings.txt,Reports/,khdb-shards/, andkhdb-manifest.json. Exception:khdb.txthas been tracked since the first commit, so the ignore rule does not apply to it. Do notgit rmit casually - client clones have a locally modifiedkhdb.txt, and an upstream deletion makes theirgit pullfail.