Commit Graph
119 Commits
Author SHA1 Message Date
tomas.kracmar 2efd06daa8 fix: sample settings' DC lines used a real former client's domain suffix
Domain1Name/Domain2Name were already proper placeholders (domain1.local, domain2.com) but their
paired DC lines still had xxx.rdm.cz / yyy.st.sk - a real former client's domains, left over from
an early edit. Match the placeholder domain.
2026-11-06 14:33:31 +01:00
tomas.kracmar 1193173a9d Release v2.5.0: arrow-key menu, KHDB backup/rebuild fixes, replication pre-check fix 2026-11-06 09:21:31 +01:00
tomas.kracmar 02274891b3 chore(release): v2.5.0 2026-11-06 09:21:23 +01:00
tomas.kracmar 20423b4404 feat(menu): arrow-key navigation for Elysium.ps1
Console.ReadKey + cursor-painted highlight, no new dependency - works on 5.1 Desktop and 7.
Number keys still jump straight to and pick an item. Falls back to the old plain Read-Host
prompt when input is redirected or the host has no real console. The keypress-to-selection
logic (Resolve-ElysiumMenuKeyPress) is a pure function in Private/Menu.ps1 so it's covered by
Pester without a real terminal.
2026-11-06 09:19:26 +01:00
tomas.kracmar 5714570ad2 fix(storage): detect a download that closed before Content-Length and retry
HttpClient's GetAwaiter().GetResult() on ReadAsStreamAsync returns once headers arrive; a
connection that then closes early leaves CopyTo finishing normally with a short file instead of
throwing. Compare the written length against the advertised Content-Length and treat a mismatch
as a transient failure. FakeStorage.ps1 can now simulate this (keys containing '/short/').
2026-11-06 09:16:55 +01:00
tomas.kracmar 256a9e7dd2 fix(khdb): verify the existing file's size before skipping a rebuild
The skip-rebuild check only compared the manifest hash in khdb-build.sha256; it never checked that
khdb.txt on disk still matched what that marker was written for. khdb.txt is tracked in git while the
shard cache and the marker are not, so anything that replaces khdb.txt's content without touching the
manifest or shards (a git checkout/pull among them) left the updater trusting a stale marker and
keeping the wrong file. The marker now also records the built file's size and both must match to skip.
2026-11-06 08:24:54 +01:00
tomas.kracmar 5eeb5b984b fix: tracked sample khdb.txt was not sorted, mixed case, and had a duplicate
Present since the first commit. DSInternals/Resolve-DSInternalsWeakHashFile requires a sorted,
upper-case, de-duplicated file; this sample failed its own repo's validator. Harmless once a real
KHDB is downloaded, but anyone running Test-WeakADPasswords before their first Update-KHDB hit
'not sorted alphabetically at line 4'.
2026-11-06 08:21:23 +01:00
tomas.kracmar 31d03d9495 fix: typo in the DCSync diagnostic dump header 2026-11-06 08:08:13 +01:00
tomas.kracmar 8356cfc23d fix(preflight): accept tokenGroups as SecurityIdentifier objects
The replication-rights pre-check cast every tokenGroups entry to byte[], which fails when the
ActiveDirectory module already returns SecurityIdentifier objects ("Cannot convert S-1-5-32-545 ... to
System.Byte[]"), so the check was skipped with a warning. Handle both forms.
2026-11-06 08:08:06 +01:00
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
tomas.kracmar a945960cef fix(khdb): fail clearly when a stale compiled type is loaded in the session
Add-Type cannot replace a type that an older build of KhdbMerge.ps1 already defined, so
an updated PasswordQuality.ps1 failed with "does not contain a method named 'Inspect'".
Check for the newest method after the guarded Add-Type and tell the operator to start a
new PowerShell session.
2026-11-06 08:02:34 +01:00
tomas.kracmar 69c8185697 perf(khdb): compiled check of the weak-hash file before the DSInternals test
Resolve-DSInternalsWeakHashFile read the whole KHDB with a per-line
PowerShell loop (regex, Trim, Split, ToUpper, comparisons) to decide
whether DSInternals could use it as is, and a second such loop to
rewrite it if not. On the real 1.3 billion-hash KHDB that is the same
hours-long cost the rebuild had before the compiled merge, paid at the
start of every Test-WeakADPasswords run.

- Elysium.KhdbText.Inspect does the check in one pass with the same
  rules and messages: invalid content and wrong order throw, legacy
  HASH:count entries and duplicates are counted.
- Elysium.KhdbText.WriteNormalized does the rewrite when needed.
- TryParse is shared with the merge's Normalize.
- The resolver announces the file and its size before checking.
- Blank lines now also mark the file as needing normalization; before,
  they were handed to DSInternals unchanged.

Measured on pwsh 7 (macOS), 5,000,000 hashes: clean file 1.6 s with no
copy; lowercase "HASH:3" file 13.8 s including the rewrite. 40/40
Pester tests pass; new test covers blank and padded lines. The Windows
PowerShell 5.1 timing on the real KHDB is still to be measured.
2026-11-05 19:17:33 +01:00
tomas.kracmar 59e187e9f0 perf(khdb): compiled merge and validation; skip rebuild when unchanged
The combined khdb.txt was built and validated with PowerShell code per
hash line. Each line paid a function call, a regex, a split and an
uppercase conversion, then a second regex pass validated the output.
A full KHDB is hundreds of millions of lines, so the rebuild took
hours on Windows PowerShell 5.1 - and on the VM it ran overnight and
had not finished. The step printed nothing, so it looked hung.

- KhdbMerge.ps1 (new): Elysium.KhdbMerger appends shards in prefix
  order with the same rules as before (32 hex, optional ":digits"
  suffix dropped, uppercase output, global sort enforced, duplicates
  removed and counted) and Elysium.KhdbText.Validate checks a finished
  file in one pass. Compiled with Add-Type, so it runs unchanged on
  Windows PowerShell 5.1 and PowerShell 7 with no extra install.
- Merge-ShardsToFile and Validate-KHDBFile keep their signatures and
  error messages; the per-line Convert-KHDBLineToHash is removed.
  Merge-ShardsToFile prints progress per shard and a duplicate count.
- Update-ElysiumKhdb skips the rebuild when the manifest hash equals
  the one recorded by the last successful build, nothing was downloaded
  or removed, and khdb.txt exists. The khdb-build.sha256 marker is
  written only after the new file is moved into place, so a failed run
  cannot leave a state that skips a needed rebuild.

Measured on pwsh 7 (macOS): 5,000,000 hashes in 256 shards merged in
3.6 s and validated in 1.2 s. The Windows PowerShell 5.1 timing still
needs measuring on the VM.

Tests: 39/39 pass. New: lowercase and HASH:count normalization with
cross-shard duplicates removed and counted; malformed content named
by shard and line; bare or non-digit count suffixes rejected;
duplicate warning on validation; a 300,000-hash, 256-shard merge
checked against a sorted reference. Update: unchanged manifest keeps
khdb.txt (same write time), a missing khdb.txt is rebuilt with no
download needed.
2026-11-05 08:20:41 +01:00
tomas.kracmar e2a523dfda feat(report): JSON report and summary output; UPNs from the replicated accounts
The weak-password report was text only: DSInternals' formatted output
captured with Out-String, with UPNs spliced in by re-parsing that
text. Nothing downstream could consume it reliably.

- Next to the text report, Invoke-WeakPasswordTest now writes
  <domain>_WeakPasswordReport_<timestamp>.json: tool, version,
  generatedAt, domain, DC, accountsTested, and one finding per
  non-empty check (WeakPassword, LMHash, DuplicatePasswordGroups, ...)
  listing each account's logon name and UPN. Duplicate-password groups
  stay grouped. The text and UPN-only reports are unchanged.
- ConvertTo-PasswordQualityFinding builds that data generically from
  the result object's properties, so it does not depend on the exact
  set of checks a DSInternals version reports. Arrays are assembled
  with List.ToArray() rather than pipeline output, because Windows
  PowerShell 5.1's ConvertTo-Json renders pipeline-wrapped arrays as
  {"value": [...], "Count": n}.
- Test-ElysiumPasswordQuality returns a summary object: domain,
  accounts tested, finding counts per check, and the three report
  paths.
- UPNs come from the DSAccount objects already replicated for the
  test (SamAccountName -> UserPrincipalName) instead of one Get-ADUser
  query per dictionary hit; Get-UserUPN is removed. Missing UPNs still
  read "UPN not found" in the text report (null in the JSON).

Tests: the converter on a result shaped like DSInternals' (string
sets, a list of sets for duplicate groups, an empty check) - empty
checks omitted, UPNs mapped, unknown UPN null, groups preserved, no
array-wrapper artefacts in the JSON. 33/33 Pester tests pass on pwsh 7.
The JSON shape on Windows PowerShell 5.1 and the real DSInternals
result object still need the Windows run.
2026-11-04 14:22:48 +01:00
tomas.kracmar 0c3c447e5c feat: -Domain and -Credential parameters for the AD cmdlets
Test-ElysiumPasswordQuality and Send-ElysiumHashExport only worked
interactively: a Read-Host for the domain number and a credential
prompt, so nothing could run unattended.

- Both cmdlets take -Domain (a configured DomainNName, matched
  case-insensitively) and -Credential. Omitted, they prompt exactly as
  before; a supplied credential still goes through the same
  Get-ADDomain / replication-permission pre-checks.
- The root wrappers take -Domain only and forward it through the
  Windows PowerShell relaunch; a PSCredential cannot be passed on a
  powershell.exe command line, so non-interactive credentials go
  through the cmdlets.
- The two copies of the domain prompt become Select-ElysiumDomain in
  Private/Settings.ps1. An unknown name fails listing the configured
  domains; a domain without a DC fails before any credential prompt
  (the export previously only noticed later).

Verified: unit test for by-name (case-insensitive), unknown name,
missing DC, and the prompt path with Read-Host mocked (valid and
invalid number); with a fake powershell.exe on PATH both wrappers
relaunch with "-Domain contoso.local" intact; 32/32 Pester tests pass
on this commit's tree. The AD paths need the Windows run.
2026-11-04 14:22:12 +01:00
tomas.kracmar 1f2b7b12fc refactor: drop the pwsh relaunch and the Elysium.Common.ps1 loader
The pwsh relaunch existed only to get ForEach-Object -Parallel for
shard transfers. Downloads now run concurrently on Windows PowerShell
5.1 through Invoke-InModuleRunspace and the publisher no longer
uploads, so Update-KHDB.ps1, Update-LithnetStore.ps1 and Uninstall.ps1
just run in whichever PowerShell starts them.

The Windows PowerShell relaunch stays for the two AD wrappers
(Test-WeakADPasswords.ps1, Extract-NTHashes.ps1): DSInternals and
ActiveDirectory need the Desktop edition. They now dot-source
src/Elysium/Private/Relaunch.ps1 directly instead of the loader.
Restart-WithPwshIfAvailable is removed.

With no script dot-sourcing it any more, the transitional
Elysium.Common.ps1 loader is deleted; every wrapper imports the
module from src/Elysium.

AGENTS.md's edition rules and the "new script" guidance now describe
the module layout (cmdlet in Public/, export in the manifest, no
`exit` in module code); README describes 5.1/7 support.

Verified on pwsh 7: with a fake powershell.exe on PATH both AD
wrappers ask it to run themselves; Update-KHDB.ps1 -MaxParallelTransfers 3
syncs 4 shards from a local HTTP server with no relaunch; Uninstall.ps1
still cancels on a wrong answer; 31/31 Pester tests and the decrypt
round trip pass.
2026-11-04 14:16:33 +01:00
tomas.kracmar 0d8af5c52e fix(Update-KHDB): reject manifest shard names that escape the shard directory
Security. Shard names come from the downloaded manifest and were
joined onto local paths unchecked, both for the staging download and
the final Move-Item into the shard directory. A manifest served from
a compromised (or spoofed) KHDB bucket could name a shard
'../../something' with a matching SHA-256 and have that file written
outside the shard directory - outside the install directory with
enough '../' - on an admin host that also holds replication
credentials. Overwriting one of Elysium's own scripts would turn that
into code execution on the next run. TLS limits this to an attacker
who controls the storage.

Reproduced before the fix against the fake S3 store: the updater
logged "Shard '../../escaped.txt' updated." and the file appeared two
levels above the shard directory.

Validate-Manifest, which runs before any download, now rejects shard
names that are rooted, contain a '..' segment (either separator), or
contain ':' (Windows drive-relative paths, NTFS alternate data
streams). Plain relative subpaths like 'sub/00.txt' stay allowed.

Tests: unit cases for each rejected form plus an allowed subpath, and
an end-to-end case where the store serves such a manifest - the run
now fails naming the shard and nothing is written outside. 31/31
Pester tests pass.
2026-11-04 13:22:18 +01:00
tomas.kracmar 06bcd22430 refactor(storage): one HTTP storage path; server-verified uploads; parallel on 5.1
Client storage access had four implementations: raw SAS HTTP and
native SigV4 for downloads, Az.Storage cmdlets and SigV4 or AWS Tools
for the hash export upload, plus separate serial and parallel download
loops. The parallel loop needed PowerShell 7 (ForEach-Object -Parallel)
and injected helper functions into its runspaces as text through
Invoke-Expression.

Now Private/Storage.ps1 has one path:
- Get-StorageConfig: provider settings, validated up front (Azure
  account/container/SAS, S3 endpoint/bucket/keys; s3Region defaults to
  us-east-1, s3ForcePathStyle to true).
- New-StorageRequest: GET/PUT request for Azure (SAS URI) or S3
  (SigV4). A PUT carries a digest the service verifies before storing:
  Content-MD5 on Azure, the signed x-amz-content-sha256 on S3.
- Invoke-StorageDownload: streams to disk; retries network errors and
  408/429/5xx (5 attempts, 2-30 s backoff), fails at once on other
  statuses (previously a 403/404 was retried for ~30 s).
- Invoke-StorageUpload: one PUT, service error body surfaced.
- Invoke-InModuleRunspace: runs a module function per parameter set in
  a runspace pool whose sessions import the module normally - works on
  Windows PowerShell 5.1 and 7, no code injection, failures collected
  and rethrown after all workers finish.

Update-ElysiumKhdb (434 -> 186 lines) fetches the manifest with
Invoke-StorageDownload and runs Receive-KhdbShard (download, size and
SHA-256 check, move into place) per shard through the pool, so
-MaxParallelTransfers now works on 5.1 too.

Send-ElysiumHashExport (230 -> 132 lines) validates storage settings
before replicating anything and uploads with Invoke-StorageUpload. The
download-back comparison, the delete-on-mismatch branch and the
Az.Storage container probe are gone: a mismatched body is rejected by
the service and never stored, and the credentials no longer need read
or list access to the upload location.

Removed: Get-FunctionDefinitionText, New-HttpClient,
Invoke-DownloadWithRetry, Invoke-S3HttpDownloadWithRetry,
Ensure-AWSS3Module, New-S3Client, Invoke-S3PutFile/GetToFile/DeleteFile,
Get-FileSha256Hex, Get-FileChecksum; the s3UseAwsTools setting. TLS
1.2 is set once at module import.

Known limit, marked in code: MD5 is unavailable on FIPS-enforced
Windows, so Azure uploads would fail there (S3 is unaffected);
Test-ElysiumPasswordQuality already refuses FIPS hosts.

Tests now run the real HttpClient/SigV4/runspace code against
tests/FakeStorage.ps1, an S3-style store on HttpListener that, like S3,
only accepts a PUT whose body matches x-amz-content-sha256. Covered:
incremental sync with 1/2/4 runspaces, a tampered shard failing the
run while keeping the previous KHDB, the publish -> update round trip
with 8 runspaces, Azure PUT headers (Content-MD5, block blob), up-front
settings validation, an S3 upload with no read-back, a rejected upload
surfacing the service error, 404 failing without retry, and a 503
retried once. 30/30 pass on pwsh 7; mutations (404 treated as
transient, worker failures dropped) each fail exactly the matching
test. Windows PowerShell 5.1 runs are still to do.
2026-11-04 13:20:31 +01:00
tomas.kracmar cb6431c82a refactor(tools)!: make the KHDB publisher build-only and standalone
The publisher runs on the provider's macOS machine and is a separate
workflow from the client. It carried its own Azure SAS and SigV4 S3
upload code, parallel uploads via ForEach-Object -Parallel with
helper functions injected through Invoke-Expression, an -UploadOnly
mode, and storage defaults read from the client's ElysiumSettings.txt
- all through the client's Elysium.Common.ps1 loader.

It now only builds the package (shards, manifest.json, khdb-clean.txt,
invalid-hashes.txt) and depends on nothing outside itself: no loader,
no relaunch, no settings file, no credentials. Uploading is left to
the storage provider's CLI, documented in the README for aws s3 /
rclone (S3-compatible) and azcopy (Azure): shards first, manifest
last, so a client never reads a manifest that points at shards that
are not there yet. -ShardRemotePrefix stays, since it is written into
the manifest and tells clients where to fetch shards from.

Removed: Upload-AzureBlob, Invoke-S3HttpUpload, the settings and
parallel-helper setup, the -UploadOnly branch and the upload section;
parameters StorageProvider, StorageAccountName, ContainerName,
SasToken, S3*, ManifestRemotePath, SkipUpload, UploadOnly,
MaxParallelTransfers, SettingsPath. 1,191 -> 770 lines. The shard
splitter and manifest writer are untouched.

BREAKING for the provider workflow only: existing invocations with
-SkipUpload or storage parameters now fail with "parameter cannot be
found"; clients are unaffected.

Verified: an AST check finds no calls to anything not defined in the
script or built into PowerShell; the publish -> update round-trip
test passes without -SkipUpload; 23/23 Pester tests pass.
2026-11-04 13:12:57 +01:00
tomas.kracmar a7f350230b fix(Prepare-KHDBStorage): actually write invalid-hashes.txt
The summary says "Invalid lines saved to .../invalid-hashes.txt" and
prints samples, but the file was always empty. $ensureInvalidWriter
is a scriptblock invoked with `&`, so it runs in a child scope:
`$invalidWriter = New-Object StreamWriter(...)` created a variable
local to that call, the outer $invalidWriter stayed $null, and every
`if ($invalidWriter) { ...WriteLine() }` was skipped. Same class of
bug as the $meta counter fixed in 06e7607.

Side effect: each invalid line opened another StreamWriter on the
same file (FileShare.Read) and never disposed it. macOS does not
enforce .NET share modes, so this only showed up as the empty file
here; on Windows the second open is expected to throw a sharing
violation and abort the publish once the input has two or more
invalid lines (not verified on Windows).

The writer now lives in a hashtable (`$invalidOutput.Writer`), which
the scriptblock mutates by reference; all 14 uses switched over.

Found by the new publish -> update round-trip test, included here:
tools/Prepare-KHDBStorage.ps1 -SkipUpload on 400 pre-sorted hashes
with mixed case, HASH:count suffixes, adjacent duplicates and a junk
line, then Update-ElysiumKhdb consumes the package. Asserts the junk
line lands in invalid-hashes.txt and the client rebuilds exactly the
sorted, unique, upper-case set. Before the fix: invalid-hashes.txt
empty (0 bytes with two junk lines). After: both lines written;
23/23 Pester tests pass.
2026-11-04 13:04:46 +01:00
tomas.kracmar ffccedb439 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).
2026-11-04 13:04:10 +01:00
tomas.kracmar 4fe884e658 refactor(Extract-NTHashes): move the export into the module as Send-ElysiumHashExport
Fourth root script converted, same mechanical approach as
Test-ElysiumPasswordQuality (AST line ranges, then a line-by-line
comparison ignoring indentation that shows only these differences):

- Script body -> src/Elysium/Public/Send-ElysiumHashExport.ps1
  (exported, [CmdletBinding()], comment-based help).
- Protect-FileWithAES -> Private/Crypto.ps1 (the ELY2 format in one
  place). tests/test_decrypt.py now dot-sources that file instead of
  pulling the function out of the script's AST.
- S3 put/get/delete, Get-FileSha256Hex and Get-FileChecksum ->
  Private/Storage.ps1; Normalize-ReportPath -> Private/Settings.ps1.
- The script's own Domain<N> loop -> the shared
  Get-DomainDetailsFromSettings; the only difference was a
  Domain<N>DA value that nothing read.
- The hash export's Out-File gets an explicit -Encoding utf8 (the
  value the script-level $PSDefaultParameterValues default supplied),
  so that session-global default and $OutputEncoding are dropped.
- Transcript via the shared helper (same extract-hashes-*.log name),
  $scriptRoot -> $InstallRoot; the completion message moves to the
  wrapper.

Extract-NTHashes.ps1 is now a thin wrapper (relaunch under
powershell.exe, import module, call the cmdlet).

Verified on macOS: decrypt round trip passes against Crypto.ps1, 22/22
Pester tests pass, and the cmdlet runs through settings to its
passphrase check and writes its transcript. The AD extraction and
upload need a Windows run.
2026-11-04 13:01:26 +01:00
tomas.kracmar 23eac693be refactor(Test-WeakADPasswords): move the AD test into the module as Test-ElysiumPasswordQuality
Third root script converted. This one cannot be exercised end-to-end
without a Windows host and a domain, so the move is mechanical: the
split used the script's own AST (function and statement line ranges),
and a line-by-line comparison ignoring indentation shows only the
intended differences below.

- Script body -> src/Elysium/Public/Test-ElysiumPasswordQuality.ps1
  (exported, [CmdletBinding()], comment-based help).
- Its helpers -> Private/PasswordQuality.ps1; the inner
  Test-WeakADPasswords function is renamed Invoke-WeakPasswordTest.
  Several of them read variables the cmdlet sets ($runningInPSCore,
  $onWindows, $reportPathBase, $timestamp, $header, $footer) through
  dynamic scoping, exactly as they read script-level variables before;
  the file header says so, and they become parameters in a later step.
- Get-DomainDetailsFromSettings -> Private/Settings.ps1.
- The inline KHDB path resolution becomes Get-KhdbPath (same
  semantics); transcript via the shared helper; $scriptRoot ->
  $InstallRoot.
- `exit` / `exit 0` -> `return`: inside a module function, exit would
  end the operator's whole PowerShell session.
- Dropped the script-level $PSDefaultParameterValues /
  $OutputEncoding block: both Out-File calls already pass
  -Encoding utf8, nothing else writes files or calls native commands,
  and in a cmdlet it would mutate the caller's session-global table.
  Dropped the forced $VerbosePreference = 'SilentlyContinue', so
  -Verbose now works.

ActiveDirectory/DSInternals are now imported from inside the module,
so they load into the module's session state instead of the global
one. Checked with stand-in modules: Get-Module (used by
Import-CompatModule and the DSInternals version check) still sees
them from module code, their commands are callable from module code,
and nothing leaks into the caller's session.

Test-WeakADPasswords.ps1 is now a thin wrapper (relaunch under
powershell.exe, import module, call the cmdlet).

Tests: domain list parsing; Resolve-DSInternalsWeakHashFile on a
clean file (passed through), a legacy file (case, HASH:count and
duplicates normalized into a temp file), and unsorted/malformed files.
22/22 Pester tests pass. On macOS the cmdlet runs through settings
and domain parsing (with -Verbose) up to its Windows-only guard and
writes its transcript. Needs a Windows run against a domain.
2026-11-04 12:58:55 +01:00
tomas.kracmar 50dcf8c1b7 refactor(Update-LithnetStore): move the importer into the module as Update-ElysiumLithnetStore
Second root script converted to a module cmdlet, same pattern as
Update-ElysiumKhdb:

- The script body -> src/Elysium/Public/Update-ElysiumLithnetStore.ps1,
  exported, same parameters.
- Get-ListFromSetting and Resolve-ExistingPath -> Private/Settings.ps1.
  The script's own Get-BooleanSetting copy is dropped for the shared
  one (TryParse instead of Convert.ToBoolean; both accept exactly
  true/false and fall back to the default for anything else).
- The inline default-KHDB resolution becomes Get-KhdbPath in
  Private/Khdb.ps1 (InstallationPath + WeakPasswordsDatabase via
  Get-InstallationPath), for the other scripts to reuse.
- Transcript via the shared Start/Stop-ElysiumTranscript; $PSScriptRoot
  becomes $InstallRoot.

Update-LithnetStore.ps1 is now a thin wrapper (relaunch under pwsh,
import module, call the cmdlet with the bound parameters).

Tests, with global stub functions standing in for the Lithnet cmdlets
so they can be mocked on any OS: default KHDB under
InstallationPath/WeakPasswordsDatabase plus settings and parameter
sources each go to the right import cmdlet; HIBP sync on/off;
Close-Store runs when an import fails; a missing KHDB names the path.
18/18 Pester tests pass. The wrapper also ran end-to-end against a stub
LithnetPasswordProtection module on PSModulePath: all three lists
imported, store closed, transcript written under Reports/logs.
2026-11-04 12:54:45 +01:00
tomas.kracmar 262b8ae0b8 fix(Update-LithnetStore): import lists instead of crashing on the first one
The three import loops iterated `$set.ToArray() | Sort-Object` over
HashSet[string] collections. HashSet<T> has no ToArray instance
method - that is a LINQ extension method, which PowerShell does not
bind - so member-access enumeration applied .ToArray() to each string
in the set and threw "[System.String] does not contain a method named
'ToArray'". An empty set enumerates nothing and passes silently, but
the hash list is never empty (configured sources, or the default KHDB,
otherwise the script throws earlier). So every run opened the store,
crashed on the first import, and closed it again with nothing
imported. Same behavior on Windows PowerShell 5.1 and PowerShell 7.

Pipe the sets into Sort-Object directly, which enumerates them.

Found by the Pester test written for the upcoming module conversion.
Reproduced and verified end-to-end with a stub LithnetPasswordProtection
module on PSModulePath: before, Open-Store -> ToArray error ->
Close-Store; after, the KHDB, plaintext and banned-word lists are each
imported and the store is closed.
2026-11-04 12:54:07 +01:00
tomas.kracmar 37a2baa5f0 chore: ignore generated khdb-package/shards/ 2026-11-04 12:51:52 +01:00
tomas.kracmar dabf543360 refactor(Update-KHDB): move the updater into the module as Update-ElysiumKhdb
First root script converted to a module cmdlet. Behavior is unchanged;
the code moves mostly verbatim:

- Update-KHDB (the function) -> src/Elysium/Public/Update-ElysiumKhdb.ps1,
  exported, with comment-based help and [CmdletBinding()]. It now sets
  TLS 1.2 itself, since the module may be imported without the script.
- Manifest/shard/merge/validation helpers -> Private/Khdb.ps1.
- HTTP download helpers (Azure SAS, native SigV4 S3, retry) ->
  Private/Storage.ps1; Get-BooleanSetting -> Private/Settings.ps1.
- The per-script Start/Stop-*Transcript pair -> one shared
  Start/Stop-ElysiumTranscript in Private/Transcript.ps1 (the other
  scripts switch to it as they are converted).
- $scriptRoot becomes $InstallRoot: the repo root in both the module
  (two levels above src/Elysium) and the Elysium.Common.ps1 loader.
  Settings, KHDB and Reports stay where they are for now.

Update-KHDB.ps1 is now a thin wrapper: relaunch under pwsh as before,
import the module from src/Elysium, call Update-ElysiumKhdb with the
bound parameters. The menu and direct invocations are unchanged.

Tests: manifest validation, out-of-order merge, empty KHDB, and an
end-to-end Update-ElysiumKhdb run against a fake Azure container with
only Invoke-DownloadWithRetry mocked - first sync (case and HASH:count
normalization, ordered merge), no-op second run (manifest only), one
changed shard plus removal of a shard the manifest no longer lists.
14/14 Pester tests pass. Separately, the wrapper ran the real HTTP
code against a local stand-in for an S3-compatible endpoint, on both
the serial and the PowerShell 7 parallel path (helpers injected into
runspaces from module scope), and produced the same merged KHDB.
2026-11-04 11:54:03 +01:00
tomas.kracmar 3180d4ea75 fix(Update-KHDB): actually accept -MaxParallelTransfers
The README documents `.\Update-KHDB.ps1 -MaxParallelTransfers 8`, but
the script had no param() block: -MaxParallelTransfers landed in
$args, Update-KHDB was called with no arguments, and PowerShell 7
always used the function's default of 5 concurrent transfers. The
relaunch forwarded it as an unbound argument, with the same result.

The script now declares the parameter (same 1-64 range as the
function) and passes $PSBoundParameters through.

Verified against a local HTTP server standing in for an S3-compatible
endpoint: before, -MaxParallelTransfers 1 still logged "up to 5
concurrent transfer(s)"; after, 1 downloads serially, 4 runs the
parallel path, and 99 is rejected by ValidateRange.
2026-11-04 11:53:41 +01:00
tomas.kracmar ffda83f4f2 test: add Pester tests for settings, storage URI and SigV4 helpers
Locks down current behavior of the helpers in src/Elysium/Private
before the storage layer is rewritten (one HttpClient path, Windows
PowerShell 5.1 only):

- Read-KeyValueSettingsFile: comments, blank and malformed lines,
  quote stripping, '=' inside values (SAS tokens), missing file;
  Read-ElysiumSettings throws on a missing file.
- Combine-StoragePath, Build-BlobUri (SAS with/without leading '?',
  percent-escaping preserved, empty SAS rejected), BuildS3Uri
  (path-style and virtual-host with a non-default port).
- BuildAuthHeaders: full Authorization header for a path-style GET
  and a virtual-host PUT on port 9000, with Get-Date mocked. The
  expected signatures were generated by botocore 1.43 (S3SigV4Auth)
  from the same inputs, so they come from an independent
  implementation rather than from this code.

8/8 pass on pwsh 7 with Pester 5.9.1. Mutation check: dropping the
port from the signed Host header fails exactly the port-9000 test.
2026-11-04 11:48:04 +01:00
tomas.kracmar 05a09d82aa refactor: make the module manifest the only version source
The project version was stamped into the banner of every file and
kept in sync by Bump-Version.ps1, which rewrote them with regexes.
It had already drifted: ElysiumSettings.txt.sample still said 2.4.4.

Now that src/Elysium/Elysium.psd1 carries ModuleVersion and both the
module and the Elysium.Common.ps1 loader read $ElysiumVersion from it,
the banner "Version:" lines and Bump-Version.ps1 have no job left.
Removed both. Releasing is: change ModuleVersion, add the CHANGELOG
entry, commit, tag - documented in the README's versioning section.

AGENTS.md: project structure now lists the module layout, and agents
are told not to add version numbers back into banners.
2026-11-04 11:45:51 +01:00
tomas.kracmar f18becde1d refactor: add Elysium module skeleton, move shared helpers into it
First step of turning the script collection into a PowerShell module.
src/Elysium/ gets a manifest (Elysium.psd1, now the single source of
the version) and a root module that dot-sources Private/ and Public/.

The 23 helpers from Elysium.Common.ps1 move verbatim into
src/Elysium/Private/, split by concern: Relaunch.ps1, Settings.ps1,
Storage.ps1 (Azure SAS, storage paths, SigV4/S3, parallel helper
injection) and AdPreflight.ps1. Nothing is exported yet.

Elysium.Common.ps1 becomes a transitional loader: it reads the
version from the manifest and dot-sources the Private files, so every
root script that dot-sources it gets exactly the same functions in
its own scope as before. No script changes in this commit.

The module sets $ErrorActionPreference = 'Stop' itself: module
functions resolve preference variables through the module scope, so
the callers' setting would not reach the cmdlets added later.

Verified on pwsh 7: Test-ModuleManifest passes; the module imports
with all 23 functions visible in module scope (so Get-Command-based
parallel helper injection keeps working once code moves in); a script
dot-sourcing the loader sees the same version and helpers, and the
relaunch still targets the calling script with its parameters; all
.ps1 files parse.
2026-11-04 11:45:10 +01:00
tomas.kracmar 63d55ef1be fix(Elysium.Common): relaunch the calling script, not Elysium.Common.ps1
Invoke-RestartWithExecutable built its command line from
$PSCommandPath. Inside a function, that is the file the function is
defined in - Elysium.Common.ps1 - not the script that asked to be
relaunched. So every relaunch ran the helper file (which only defines
functions), got exit code 0, and the caller then exited. The actual
script never ran and nothing reported an error.

Affected whenever a relaunch fires: Update-KHDB, Prepare-KHDBStorage,
Update-LithnetStore and Uninstall started from Windows PowerShell on
a host with pwsh installed (menu options 1, 4 and 5 included), and
Extract-NTHashes / Test-WeakADPasswords started directly from pwsh.
Menu options 2 and 3 were unaffected because the menu already starts
those under powershell.exe, where no relaunch fires.

Restart-WithPwshIfAvailable and Restart-WithWindowsPowerShellIfAvailable
now pass $MyInvocation.PSCommandPath (the script that called them)
down as -ScriptPath.

Verified on pwsh 7 with a fake powershell.exe on PATH that prints its
arguments: the old helper asked it to run Elysium.Common.ps1, the
fixed one runs the calling script with its bound parameters
(-MaxParallelTransfers 8 -Force) forwarded. Not yet run on a real
Windows PowerShell 5.1 host.
2026-11-04 11:41:44 +01:00
tomas.kracmar f69356da45 docs(AGENTS): document ELY2 format, decrypt test, khdb.txt tracking 2026-11-04 10:31:08 +01:00
tomas.kracmar bf14a254b4 fix(Update-LithnetStore): resolve KHDB via settings, add transcript, use shared parser
The default hash source ignored InstallationPath/WeakPasswordsDatabase and
always looked for khdb.txt next to the script; it now resolves the same path
as Update-KHDB.ps1 and Test-WeakADPasswords.ps1. The script also writes a
transcript to Reports/logs/ and uses Read-KeyValueSettingsFile from
Elysium.Common.ps1 instead of its own copy.

CHANGELOG [Unreleased] also records the earlier fixes on this branch.
2026-11-04 10:31:07 +01:00
tomas.kracmar 84815eef09 fix(Test-WeakADPasswords): stop marking PSGallery as Trusted on the host
Ensure-NuGetAndPSGallery silently ran Set-PSRepository PSGallery
-InstallationPolicy Trusted as a side effect of installing
DSInternals, permanently changing the host's module trust policy for
every later Install-Module by anyone on that machine.

Removed it. The operator has already confirmed the install at this
point, and both install calls (Install-Module and Save-Module) pass
-Force, which skips the untrusted-repository prompt for that call
only.
2026-11-04 09:25:53 +01:00
tomas.kracmar 2b82dbd1f0 fix(Test-WeakADPasswords): relaunch under Windows PowerShell like Extract-NTHashes
The menu routes option 2 to powershell.exe, but running the script
directly under pwsh skipped that: unlike Extract-NTHashes.ps1 it never
called Restart-WithWindowsPowerShellIfAvailable, despite AGENTS.md
saying it does. It then loaded DSInternals via -UseWindowsPowerShell
implicit remoting, which hands back deserialized objects instead of
live DSAccount instances for the Get-ADReplAccount |
Test-PasswordQuality pipeline.

Added the same relaunch call right after the common helper import.
The -UseWindowsPowerShell path stays as the fallback for hosts with
no powershell.exe.

Parse-checked only; the relaunch itself needs a Windows host.
2026-11-04 09:25:23 +01:00
tomas.kracmar 89c5e21002 fix(decrypt): read ELY2 and use PBKDF2-SHA256 to match the PowerShell side
decrypt.py could not decrypt any current export:
- It did not know the ELY2 format introduced in v2.4.6, so ELY2 files
  fell through to the legacy branch and failed.
- Its ELY1 branch called pycryptodome's PBKDF2 with the default PRF
  (HMAC-SHA1), while Extract-NTHashes.ps1 has used HMAC-SHA256 since
  ELY1 was introduced, so ELY1 files never decrypted either.

Now reads ELY2 (HMAC-SHA256 verified before decrypting, keys taken
from one 64-byte PBKDF2 output exactly like the two sequential
Rfc2898DeriveBytes.GetBytes(32) calls), ELY1, and the legacy format.
Key derivation uses stdlib hashlib.pbkdf2_hmac with the passphrase
encoded as UTF-8, matching .NET's string overload (pycryptodome
defaulted to latin-1). Padding is checked with Crypto.Util.Padding
instead of a length-byte range check.

Also: the passphrase prompt no longer echoes (getpass), an input path
not ending in .enc is refused instead of being overwritten by the
output, and failures exit non-zero.

tests/test_decrypt.py encrypts with the real Protect-FileWithAES
(extracted from Extract-NTHashes.ps1's AST, so the script body never
runs) via pwsh and decrypts with decrypt.py: ASCII and non-ASCII
passphrases round-trip; a wrong passphrase and a flipped ciphertext
bit are rejected by the HMAC check. With the old SHA1 derivation
patched back in, the test fails.
2026-11-04 09:24:37 +01:00
tomas.kracmar aba74fc4c2 fix(Uninstall): require confirmation; fix swapped menu numbers in docs
README.md documented Lithnet as menu option 5 and Uninstall as option
4, the reverse of the actual menu (and of Elysium.ps1's own help
block). Uninstall.ps1 recursively force-deletes the install directory
- reports, KHDB and settings included - with no prompt, so an
operator following the README to update the Lithnet store wiped the
tool instead.

Fixed the numbering in both docs, and Uninstall.ps1 now requires
typing YES (case-sensitive) before deleting anything. -Force skips
the prompt for unattended removal; Restart-WithPwshIfAvailable
already forwards bound switches to the relaunched process.

Verified on scratch copies: answering "yes" cancels and leaves the
directory intact, "YES" deletes it.
2026-11-04 09:22:44 +01:00
tomas.kracmarandClaude Sonnet 5 2d90656e5c Release v2.4.6: security/correctness fixes from full codebase review
Consolidates this session's review findings, each already fixed and
committed individually: Uninstall.ps1 deleting the wrong directory,
plaintext passphrase handling, a DCSync ACL pre-check bypass via UPN
credentials, an orchestrator that crashed instead of returning to its
menu, plaintext-hash exposure window and unauthenticated AES export
in Extract-NTHashes.ps1, KHDB shard-size/backup/dedup issues in
Prepare-KHDBStorage.ps1 and Update-KHDB.ps1, and assorted resource
leaks. See CHANGELOG.md for the full list.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-29 12:10:26 +02:00
tomas.kracmarandClaude Sonnet 5 5b761d8d56 fix(Extract-NTHashes): add HMAC-SHA256 to the AES export (breaking format bump to ELY2)
Protect-FileWithAES used AES-256-CBC with no integrity check. A wrong
passphrase or corrupted/tampered ciphertext just decrypts to garbage
(or an unhelpful padding exception) instead of being detected.

Derives a second 32-byte key from the same PBKDF2 stream (the AES key
and HMAC key are sequential, non-overlapping ranges of one
Rfc2898DeriveBytes instance) and computes HMAC-SHA256 over
magic+salt+iv+ciphertext (encrypt-then-MAC), appended as a trailer.
Bumped the format magic from 'ELY1' to 'ELY2' so old and new files
are distinguishable.

This is a breaking change for whatever external tooling decrypts
these exports (this repo only ever encrypts - decryption happens on
a separate air-gapped machine per the README's FAQ) - documented the
new layout and the break in the README.

Verified with an isolated round-trip test (function extracted,
dot-sourced, paired with a hand-written decrypt+HMAC-verify): correct
passphrase round-trips cleanly, a wrong passphrase is rejected via
HMAC mismatch, and a single flipped ciphertext byte is also rejected
via HMAC mismatch, in all cases before any AES decryption is
attempted.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-29 12:10:04 +02:00
tomas.kracmarandClaude Sonnet 5 80199ad7d6 fix(Extract-NTHashes): pin plaintext hash export to UTF-8
Out-File defaults to UTF-16LE on Windows PowerShell 5.1 (Desktop) and
UTF-8 on PowerShell 7 (Core), so the encoding of the transient
plaintext hash export depended purely on which host happened to run
the script - inconsistent with Test-WeakADPasswords.ps1/
Update-KHDB.ps1, which already pin this. Applied the same
$PSDefaultParameterValues['Out-File:Encoding'] = 'utf8' pattern.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-29 12:06:12 +02:00
tomas.kracmarandClaude Sonnet 5 eea0ddf932 fix(Update-KHDB): dispose HttpResponseMessage on download
Invoke-DownloadWithRetry disposed the response stream and file handle
but never the HttpResponseMessage itself returned by GetAsync,
leaking one per shard download (the S3 code path already disposes
its response object). Added a finally block per attempt to dispose
it on both the success and retry/failure paths.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-29 12:05:30 +02:00
tomas.kracmarandClaude Sonnet 5 2f0ff9085a fix(Prepare-KHDBStorage): reject manifest shard names outside shard root
In -UploadOnly mode, entry.name from the parsed manifest.json was
used directly in Join-Path (local read) and as the remote object key
with no path-traversal check. A tampered local manifest.json
(requires prior local write access to the shard directory) with a
name like '..\..\secrets.txt' could make the upload step read and
upload an arbitrary local file under an attacker-chosen remote key.
Now resolves each shard's full path via GetFullPath and rejects any
entry that resolves outside the shard root, before it's added to the
list actually used for reads/uploads. Verified the resolved-path
containment check against normal relative names (allowed) and '..'
traversal attempts (blocked).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-29 12:04:43 +02:00
tomas.kracmarandClaude Sonnet 5 03ceec9d5e fix(Elysium.Common): dispose DirectoryEntry/ADSI objects
Test-ReplicationPermissions and Test-DCClockSkew each build a
DirectoryEntry (holding a live ADSI/COM binding, with a plaintext
credential) and never call .Dispose(), leaking the underlying COM
resource on every invocation - noticeable across a run that checks
multiple domains/DCs in one session. Added finally blocks to dispose
both.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-29 12:03:31 +02:00
tomas.kracmarandClaude Sonnet 5 06e7607eff fix(Prepare-KHDBStorage): fast-path dedup, and a scope bug hiding it
Two related bugs in Split-KhdbIntoShards:

1. The fast path for plain 32-hex-char lines wrote every line
   straight to its shard with no deduplication, unlike the slow path
   which merges adjacent duplicate hashes via a per-shard pending-line
   buffer. Routed the fast path through the same pending-line buffer
   so adjacent duplicates are dropped there too.

2. While fixing that, found $total (the valid-entry counter) was a
   plain scalar incremented inside $processHashLine, which is invoked
   via the call operator (&). Scriptblocks invoked with & run in
   their own child scope, so '$total++' inside them silently
   incremented a local shadow copy and never updated the real
   counter in the enclosing function - meaning TotalEntries/
   validEntries (used in the returned result, the checkpoint state,
   and the live progress status) were wrong on every run, previously
   masked because actual shard file writes go through $state.Writer
   objects (reference types, unaffected by the scoping issue).
   Moved the counter onto $meta (already a hashtable used the same
   way for TotalLines/InvalidLines/etc.) so it mutates by reference
   across the scope boundary.

Verified both with an isolated test harness (function extracted and
dot-sourced, no AD/Windows dependency): adjacent AAAA/CCCC duplicates
in a 6-line sample now collapse to 3 shard entries, and TotalEntries
correctly reports 3 instead of the previous 0/wrong value.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-29 12:01:28 +02:00
tomas.kracmarandClaude Sonnet 5 9bef6d50f5 fix(Test-WeakADPasswords): prevent report column truncation
$testResults | Out-String used the default formatter width, which
truncates long columns at the console/default width. The report text
is re-parsed line-by-line to attach "UPN:" annotations, taking the
first whitespace token as SamAccountName - a truncated account name
would silently fail to match $dictionarySamToUpn and drop the
annotation with no error. Pass -Width 4096 to avoid truncation.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-29 11:54:47 +02:00
tomas.kracmarandClaude Sonnet 5 d155276366 fix(Extract-NTHashes): remove mismatched blob after checksum failure
On upload checksum mismatch, the script warned and preserved the
local encrypted file but left the already-uploaded, corrupt blob live
in remote storage under its normal name - discoverable only via an
easy-to-miss console warning, and fetchable as if it were good data
by any downstream consumer. Added Invoke-S3DeleteFile (SigV4-signed,
mirrors the existing Put/Get helpers) and now delete the mismatched
blob from S3 (AWS Tools or native HTTP path) or Azure Blob Storage
right after detecting the mismatch.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-29 11:54:21 +02:00
tomas.kracmarandClaude Sonnet 5 867fb6427d fix(Update-KHDB): cap KHDB backup retention
Every successful update created a new khdb.txt.bak-<timestamp> with
no cleanup anywhere, so a recurring scheduled job accumulated one
full-size backup per run indefinitely. Now keeps only the 5 most
recent backups, pruning older ones after each new backup is created.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-29 11:53:26 +02:00
tomas.kracmarandClaude Sonnet 5 1440b65b9a fix(Update-KHDB): accept manifest's full supported shardSize range
Validate-Manifest hardcoded shardSize -ne 2 as an error, but
Prepare-KHDBStorage.ps1's -ShardSize parameter validly accepts 1-8.
Merge-ShardsToFile doesn't use shardSize for anything structural - it
reads shard files purely by name/content - so the check added no
safety, only rejected manifests produced with any supported shard
size other than 2. Widened the check to the same 1-8 range instead.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-29 11:52:58 +02:00
tomas.kracmarandClaude Sonnet 5 5691463bd3 fix(Elysium): catch sub-script errors instead of crashing the menu
The menu loop had try/finally with no catch. Update-KHDB.ps1,
Test-WeakADPasswords.ps1, and Extract-NTHashes.ps1 all run under
$ErrorActionPreference = 'Stop' and re-throw on failure, so any
runtime error (bad credentials, unreachable DC, network failure)
propagated uncaught through the parent and killed the whole
orchestrator instead of returning to the menu. Wrapped the switch in
try/catch so a failed option reports the error and redisplays the
menu.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-29 11:52:13 +02:00