refactor: move provider-side tools to tools/
Prepare-KHDBStorage.ps1 (publishes the KHDB) and decrypt.py (decrypts client hash exports on the provider's cracking machine) are only ever run by the tool provider, but sat next to the client scripts that every customer clones. Moved both to tools/ so the client surface (root wrappers + src/Elysium) is separate from provider tooling; packaging the module later ships only src/Elysium. Prepare-KHDBStorage.ps1 now resolves Elysium.Common.ps1 and the default ElysiumSettings.txt from the repo root (one level up) instead of its own folder. tests/test_decrypt.py imports decrypt from tools/. README and AGENTS paths updated; AGENTS' structure listing also gets the module lines back after the settings sample, where they belong. Verified: decrypt round trip passes from the new location, and tools/Prepare-KHDBStorage.ps1 -SkipUpload runs from the repo root and produces a package (manifest, 256 shards, khdb-clean.txt).
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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'''
|
||||
|
||||
@@ -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
|
||||
}
|
||||
Reference in New Issue
Block a user