diff --git a/AGENTS.md b/AGENTS.md index fa26bea..214086c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ The tool performs three core workflows: - **Runtime:** Windows PowerShell 5.1 or PowerShell 7 (`pwsh`). - **Required PowerShell modules:** `DSInternals`, `ActiveDirectory` (RSAT). - **Optional PowerShell modules:** `Az.Storage`, `AWS.Tools.S3` / `AWSPowerShell.NetCore`, `LithnetPasswordProtection`. -- **Python 3:** `decrypt.py` requires `pycryptodome` for decrypting uploaded payload files. +- **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 @@ -27,20 +27,20 @@ The tool performs three core workflows: Elysium.ps1 # Main menu / orchestrator script Elysium.Common.ps1 # Transitional loader: dot-sources src/Elysium/Private/*.ps1 into the calling 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) -ElysiumSettings.txt.sample # Documented template for operators Update-KHDB.ps1 # Wrapper: relaunch under pwsh, then call Update-ElysiumKhdb (src/Elysium/Public) -Prepare-KHDBStorage.ps1 # KHDB publisher: split source into shards, build manifest, upload 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 -decrypt.py # Python 3 decryptor for .enc payloads (ELY2, ELY1, legacy) +tools/Prepare-KHDBStorage.ps1 # Provider only - KHDB publisher: split source into shards, build manifest, 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) @@ -100,14 +100,14 @@ There is no package manager or build system. The tool is run directly: .\Test-WeakADPasswords.ps1 .\Extract-NTHashes.ps1 .\Update-LithnetStore.ps1 -.\Prepare-KHDBStorage.ps1 -SourcePath .\khdb.txt -OutputRoot .\publish -StorageProvider S3 -SkipUpload +.\tools\Prepare-KHDBStorage.ps1 -SourcePath .\khdb.txt -OutputRoot .\publish -StorageProvider S3 -SkipUpload .\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 - an end-to-end `Update-ElysiumKhdb` incremental sync with only `Invoke-DownloadWithRetry` mocked, `Update-ElysiumLithnetStore` against stubbed Lithnet cmdlets, and the pure password-quality helpers (domain list, KHDB normalization for DSInternals). 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 `decrypt.py`. Run it after touching either side of the export format. +- `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 diff --git a/README.md b/README.md index ede4acc..71163d1 100644 --- a/README.md +++ b/README.md @@ -32,10 +32,10 @@ All scripts automatically relaunch under PowerShell 7 (`pwsh`) when it is instal Run script Elysium.ps1 as an administrator and choose option 1 (Update Known-Hashes Database). The updater now pulls a manifest plus individual hash shards (two-hex prefix layout) from the configured storage (Azure Blob or S3-compatible), verifies checksums, replaces only changed shards, and rebuilds `khdb.txt` for local use. Deleted shards listed in the manifest are removed automatically. When PowerShell 7 is available the downloader automatically fetches up to `-MaxParallelTransfers` shards in parallel (default `5`); on Windows PowerShell 5.1 it reverts to the original sequential behavior. Override the concurrency as needed when running the script directly (for example `.\Update-KHDB.ps1 -MaxParallelTransfers 8`). -To publish an updated shard set, run `Prepare-KHDBStorage.ps1` against your sorted `khdb.txt` (or point it at the directory/list of the Have I Been Pwned `.gz` slices). The helper reconstructs the full 32‑hex NTLM values (prefix + remainder), deduplicates per hash (keeping the largest count), splits by the first two hex characters, writes a manifest (`version`, `sha256`, `size`, entry counts), and can upload the resulting files directly to Azure Blob Storage (via SAS) or S3-compatible endpoints using SigV4. Invalid or malformed entries are omitted automatically, and a short report (aggregate counts + `invalid-hashes.txt`) is produced for review. Example: +To publish an updated shard set (tool provider only), run `tools/Prepare-KHDBStorage.ps1` against your sorted `khdb.txt` (or point it at the directory/list of the Have I Been Pwned `.gz` slices). The helper reconstructs the full 32‑hex NTLM values (prefix + remainder), deduplicates per hash (keeping the largest count), splits by the first two hex characters, writes a manifest (`version`, `sha256`, `size`, entry counts), and can upload the resulting files directly to Azure Blob Storage (via SAS) or S3-compatible endpoints using SigV4. Invalid or malformed entries are omitted automatically, and a short report (aggregate counts + `invalid-hashes.txt`) is produced for review. Example: ```powershell -.\Prepare-KHDBStorage.ps1 -SourcePath .\khdb.txt ` +.\tools\Prepare-KHDBStorage.ps1 -SourcePath .\khdb.txt ` -OutputRoot .\publish ` -StorageProvider S3 ` -S3EndpointUrl https://s3.example.com ` @@ -108,7 +108,7 @@ If you want to know the script was executed without collecting telemetry, set a Run script Elysium.ps1 as an administrator and choose option 3 (Extract and Send Hashes). Domains are listed in configuration order, after which the script prompts for the replication-capable account password. With valid credentials, it extracts current NTLM hashes (no history) for active accounts, compresses the results, encrypts them with the configured passphrase, and uploads the payload to the configured storage (Azure Blob or S3-compatible). A checksum-verified round-trip download confirms the upload before local artifacts are removed. -**Encrypted export format (v2.4.6+, magic `ELY2`):** `4-byte magic 'ELY2' | 16-byte PBKDF2 salt | 16-byte AES IV | AES-256-CBC ciphertext | 32-byte HMAC-SHA256`. Both keys are derived from the configured passphrase via one PBKDF2-SHA256 (100,000 iterations) byte stream: the first 32 bytes are the AES key, the next 32 are the HMAC key. The HMAC covers `magic | salt | iv | ciphertext` (encrypt-then-MAC) so a decrypt tool must verify it *before* decrypting - CBC alone doesn't detect a wrong passphrase or corrupted/tampered ciphertext, it just produces garbage or an unhelpful padding exception. This is a breaking change from the older `ELY1` format (no HMAC trailer) produced before v2.4.6; any external decryption tooling on the air-gapped cracking machine needs updating to match. The bundled `decrypt.py` reads `ELY2`, `ELY1`, and the pre-`ELY1` legacy format; `python3 tests/test_decrypt.py` checks it against the PowerShell encryptor (needs `pwsh` and `pycryptodome`). +**Encrypted export format (v2.4.6+, magic `ELY2`):** `4-byte magic 'ELY2' | 16-byte PBKDF2 salt | 16-byte AES IV | AES-256-CBC ciphertext | 32-byte HMAC-SHA256`. Both keys are derived from the configured passphrase via one PBKDF2-SHA256 (100,000 iterations) byte stream: the first 32 bytes are the AES key, the next 32 are the HMAC key. The HMAC covers `magic | salt | iv | ciphertext` (encrypt-then-MAC) so a decrypt tool must verify it *before* decrypting - CBC alone doesn't detect a wrong passphrase or corrupted/tampered ciphertext, it just produces garbage or an unhelpful padding exception. This is a breaking change from the older `ELY1` format (no HMAC trailer) produced before v2.4.6; any external decryption tooling on the air-gapped cracking machine needs updating to match. The bundled `tools/decrypt.py` reads `ELY2`, `ELY1`, and the pre-`ELY1` legacy format; `python3 tests/test_decrypt.py` checks it against the PowerShell encryptor (needs `pwsh` and `pycryptodome`). ### Update Lithnet Password Protection store Run script Elysium.ps1 as an administrator and choose option 4 (Update Lithnet Password Protection Store). diff --git a/tests/test_decrypt.py b/tests/test_decrypt.py index 4983c77..bebed25 100644 --- a/tests/test_decrypt.py +++ b/tests/test_decrypt.py @@ -8,7 +8,7 @@ import sys import tempfile ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) -sys.path.insert(0, ROOT) +sys.path.insert(0, os.path.join(ROOT, 'tools')) import decrypt # noqa: E402 ENCRYPT_PS1 = r''' diff --git a/Prepare-KHDBStorage.ps1 b/tools/Prepare-KHDBStorage.ps1 similarity index 99% rename from Prepare-KHDBStorage.ps1 rename to tools/Prepare-KHDBStorage.ps1 index 9f88103..4057766 100644 --- a/Prepare-KHDBStorage.ps1 +++ b/tools/Prepare-KHDBStorage.ps1 @@ -74,7 +74,9 @@ param( $ErrorActionPreference = 'Stop' Set-StrictMode -Version Latest -[string]$commonHelper = Join-Path -Path $PSScriptRoot -ChildPath 'Elysium.Common.ps1' +# Provider-side tool in tools/; the shared helpers and default settings live in the repo root. +$repoRoot = Split-Path -Path $PSScriptRoot -Parent +[string]$commonHelper = Join-Path -Path $repoRoot -ChildPath 'Elysium.Common.ps1' if (-not (Test-Path -LiteralPath $commonHelper)) { throw "Common helper not found at $commonHelper" } . $commonHelper Restart-WithPwshIfAvailable -BoundParameters $PSBoundParameters -UnboundArguments $MyInvocation.UnboundArguments @@ -715,7 +717,7 @@ if ($SettingsPath) { } $resolvedSettingsPath = (Resolve-Path -LiteralPath $SettingsPath).Path } else { - $defaultSettingsCandidate = Join-Path -Path $PSScriptRoot -ChildPath 'ElysiumSettings.txt' + $defaultSettingsCandidate = Join-Path -Path $repoRoot -ChildPath 'ElysiumSettings.txt' if (Test-Path -LiteralPath $defaultSettingsCandidate) { $resolvedSettingsPath = (Resolve-Path -LiteralPath $defaultSettingsCandidate).Path } diff --git a/decrypt.py b/tools/decrypt.py similarity index 100% rename from decrypt.py rename to tools/decrypt.py