https://github.com/soyuz43/ftype-audit-safe
Safe PowerShell tool for auditing and repairing Windows file type associations with backup, dry-run, and signature support.
https://github.com/soyuz43/ftype-audit-safe
audit automation code-signing file-association infosec powershell registry secure-scripting windows
Last synced: about 1 month ago
JSON representation
Safe PowerShell tool for auditing and repairing Windows file type associations with backup, dry-run, and signature support.
- Host: GitHub
- URL: https://github.com/soyuz43/ftype-audit-safe
- Owner: soyuz43
- License: mit
- Created: 2025-04-16T18:44:02.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-07-28T00:50:57.000Z (11 months ago)
- Last Synced: 2025-07-28T02:30:31.704Z (10 months ago)
- Topics: audit, automation, code-signing, file-association, infosec, powershell, registry, secure-scripting, windows
- Language: PowerShell
- Homepage: https://soyuz43.github.io/ftype-audit-safe/
- Size: 104 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
# 🔍 FtypeAudit — Safe File Association Analyzer
FtypeAudit is a hardened, security-aware PowerShell utility for **auditing**, **explaining**, and **repairing** Windows file association conflicts. It maps the semantic layers of the registry (UserChoice, SystemDefault, MRUList) while enforcing safety-first principles with optional backup and dry-run modes.
---
## Features
- **Audit file type handlers** using a structured `SafeAssociationProfile` model
- **Safe registry mutation** with dry-run simulation and optional `.reg` backup
- **Explain mode** interprets conflicts in user vs. system behavior
- **Literal mode** gives you raw technical diagnostic data
- **Force mode** enables controlled registry repair (with backup or preview)
---
## 🛠 Usage
### Basic Audit
```powershell
.\ftype-audit.ps1 .json
```
Dry Run (No Changes)
```
.\ftype-audit.ps1 .txt -DryRun
```
Backup Before Repair
```
.\ftype-audit.ps1 .docx -Backup -Clean
```
Technical Report
```
.\ftype-audit.ps1 .html -Literal
```
Explanation of Layers
```
.\ftype-audit.ps1 .html -Explain
```
#### Parameters
| Parameter | Description |
|---------------------|---------------------------------------------------------------|
| `-Path` | File or extension to analyze (e.g., `.txt`, `C:\file.pdf`) |
| `-DryRun` | Preview changes without writing to registry |
| `-Backup` | Create `.reg` backup before making any changes |
| `-BackupPath` | Custom path for registry backup file |
| `-Clean` | Perform safe cleanup of file association entries |
| `-SkipConfirmation` | Skip interactive confirmation prompts (affects -Clean, -DryRun)|
| `-Explain` | Display analysis of file association conflicts |
| `-Literal` | Output raw technical details only |
| `-IsExtension` | Treat input Path explicitly as an extension (bypass file-exists check) |
| `-AuditPython` | Run Python residue audit and exit |
| `-Help` | Show detailed help screen |
#### 🧾 **Example Output**
When analyzing a file association using the `-Explain` flag, you'll see a human-readable summary:
```plaintext
[EXPLAINED VIEW: .TXT]
Timestamp: 2025-06-24 12:45
CORE STATUS:
[+] Configuration Valid
REGISTRY ANALYSIS:
User Choice: txtfile
System Default: txtfile
Valid Handlers: 1
MRU Integrity: Intact
````
For raw technical data, use the `-Literal` flag:
```plaintext
Association Health Report: .txt
Captured at: 2025-06-24 12:45:21
[Evidence]
@{State=BrokenHandlerPath; Message=Handler resolution failed: Code.exe}
@{State=CorruptMRUOrder; Message=MRU references invalid handlers: a,e,b}
```
To preview repairs without modifying the registry, use `-DryRun`:
```plaintext
.txt : [+]
[>] Simulated repair operations:
would fix: @{State=BrokenHandlerPath; Message=Handler resolution failed: Code.exe}
would fix: @{State=CorruptMRUOrder; Message=MRU references invalid handlers: a,e,b}
```
> 🛑 Use `-Clean` to apply changes. Elevation required.
Note: `-DryRun` flags MRU entries as they exist in the registry, whereas `-Explain` shows MRU integrity after resolving only valid handlers—so a corrupt raw MRU can appear fixed once invalid handlers are filtered out.
#### 🔐 Security & Signing
This script supports safe execution in locked-down environments:
Complies with AllSigned policies if digitally signed
Use your enterprise code-signing certificate:
```
$cert = Get-ChildItem -Path Cert:\CurrentUser\My -CodeSigningCert
Set-AuthenticodeSignature -FilePath .\ftype-audit.ps1 -Certificate $cert
```
#### Module Packaging
To install as a reusable module:
- Rename script to `FtypeAudit.psm1`
+ Create a manifest:
```
New-ModuleManifest -Path .\FtypeAudit.psd1 `
-RootModule 'FtypeAudit.psm1' `
-FunctionsToExport '*' `
-Author 'Your Name' `
-Description 'Safe file association analyzer and repair tool'
```
- Import as needed:
```
Import-Module .\FtypeAudit.psd1
```