# computedocean/locksmith architecture

> Architecture diagram of the GitHub repository computedocean/locksmith, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/computedocean/locksmith
- Repository: https://github.com/computedocean/locksmith

## Overview

##### Project type and purpose
- This is an open-source PowerShell module and standalone script (“Locksmith”) designed to scan and optionally remediate misconfigurations in Active Directory Certificate Services (AD CS).
- It ships as both a module (Locksmith.psd1 + Locksmith.psm1) and a monolithic script (Invoke-Locksmith.ps1), with multiple “modes” that control output and remediation behavior.

##### File structure
- Top-level:
- Public entrypoints: Invoke-Locksmith.ps1, Public/Invoke-Locksmith.ps1
- Module files: Locksmith.psd1, Locksmith.psm1
- Scan implementations: Private/*.ps1
- Build & release scripts: Build/*.ps1, .github/workflows/**
- Documentation: Docs/, mkdocs.yml, en-US/ (help XML)
- Tests: Tests/*.ps1
- Patterns:
- “Private” folder holds individual scan/remediation functions (ESC1, ESC2,… Auditing, etc.).
- “Public” exports only the top-level cmdlet.
- Build/CI pipelines generate docs (MkDocs) and package to PowerShell Gallery.

##### README for additional insights
- Scans parameter drives selection of Private/*.ps1 modules.
- Requires ActiveDirectory and ServerManager PowerShell modules and domain-joined system.

a. Main components
1. User Interface Layer
– CLI entrypoint (Invoke-Locksmith.ps1 or module cmdlet)
2. Orchestration Layer
– Dispatcher/orchestrator in Locksmith.psm1
3. Scan & Remediation Modules
– Private/*.ps1 (one file per vulnerability type)
4. Output Renderer
– Table/List/CSV formatter, CSV writer, console writer
5. Build & Documentation Pipeline
– Build/*.ps1, mkdocs.yml, GitHub Actions
6. Tests
– Tests/*.ps1 – smoke and scenario tests
7. External Dependencies
– Active Directory Certificate Services (via ActiveDirectory module)
– ServerManager PowerShell module
– File system for CSV, help XML, docs

b. Relationships and interactions
- User invokes CLI → orchestrator loads selected scan modules → each scan module uses AD/ServerManager cmdlets to collect data → results flow to renderer or remediation functions → outputs written to console or CSV (or changes applied back to AD CS).
- Build scripts pull source code + Docs → generate MkDocs site and packaged module/artifact → GitHub Actions automate test, lint, build, and release.
- Tests simulate AD CS objects and validate scan logic against expected results.

c. Architectural patterns & design principles
- Modular scan plugins (separation of concerns per vulnerability scan).
- Single entrypoint with mode-driven behavior (Strategy pattern).
- Infrastructure abstraction: all AD interactions through PowerShell modules.
- CI/CD Pipeline as code (GitHub workflows).

d. Key technologies & frameworks
- PowerShell 5+.
- PowerShell modules: ActiveDirectory, ServerManager.
- MkDocs for documentation.
- GitHub Actions for CI/CD.
- Pester (implicitly for tests).

##### Detailed coverage
- Mode parameter branching logic in the orchestrator.
- Tests consuming Public/Private code and simulating results.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Components
    subgraph "Runtime Components" 
        direction TB
        CLI1["Invoke-Locksmith CLI (Standalone)"]:::runtime
        CLI2["Invoke-Locksmith CLI (Module)"]:::runtime
        ORCH["Locker Orchestrator<br/>Dispatch & Mode Logic"]:::runtime
    end

    %% Scan and Remediation
    subgraph "Scan & Remediation Modules" 
        direction TB
        subgraph "Scan Modules" 
            direction TB
            ESC1["Find-ESC1"]:::runtime
            ESC2["Find-ESC2"]:::runtime
            ESC3C1["Find-ESC3C1"]:::runtime
            ESC3C2["Find-ESC3C2"]:::runtime
            ESC4["Find-ESC4"]:::runtime
            ESC5["Find-ESC5"]:::runtime
            ESC6["Find-ESC6"]:::runtime
            ESC8["Find-ESC8"]:::runtime
            ESC9["Find-ESC9"]:::runtime
            ESC11["Find-ESC11"]:::runtime
            ESC13["Find-ESC13"]:::runtime
            ESC15["Find-ESC15"]:::runtime
            AUDIT["Find-AuditingIssue"]:::runtime
        end
        subgraph "Remediation Modules" 
            direction TB
            REM1["Update-ESC1Remediation"]:::runtime
            REM4["Update-ESC4Remediation"]:::runtime
        end
    end

    %% Helper Utilities & Renderer
    subgraph "Utilities & Output Renderer"
        direction TB
        HELP["Format-Result & Writer"]:::runtime
        CSVUTIL["New-OutputPath (CSV/File)"]:::runtime
        COUT["Write-HostColorized"]:::runtime
        CSVSTORE[(CSV Files)]:::data
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        ADCS["AD CS<br/>(ActiveDirectory Module)"]:::external
        SM["ServerManager Module"]:::external
    end

    %% CI/CD Pipeline & Documentation
    subgraph "Build & CI/CD Pipeline"
        direction TB
        BUILD["Build Scripts & MkDocs"]:::devops
        GHA["GitHub Actions"]:::devops
        DOCS["Documentation Site"]:::devops
    end

    %% Tests
    subgraph "Tests"
        direction TB
        T1["Compare-ADObjects"]:::devops
        T2["Invoke-TSS"]:::devops
        T3["Show-ADObjectChanges"]:::devops
        T4["TSS Specs.md"]:::devops
    end

    %% Relationships
    CLI1 --> ORCH
    CLI2 --> ORCH
    ORCH -->|loads| ESC1
    ORCH --> ESC2
    ORCH --> ESC3C1
    ORCH --> ESC3C2
    ORCH --> ESC4
    ORCH --> ESC5
    ORCH --> ESC6
    ORCH --> ESC8
    ORCH --> ESC9
    ORCH --> ESC11
    ORCH --> ESC13
    ORCH --> ESC15
    ORCH --> AUDIT
    ESC1 --> HELP
    ESC2 --> HELP
    ESC3C1 --> HELP
    ESC3C2 --> HELP
    ESC4 --> HELP
    ESC5 --> HELP
    ESC6 --> HELP
    ESC8 --> HELP
    ESC9 --> HELP
    ESC11 --> HELP
    ESC13 --> HELP
    ESC15 --> HELP
    AUDIT --> HELP
    HELP --> CSVSTORE
    HELP --> COUT
    ORCH --> REM1
    ORCH --> REM4
    REM1 --> ADCS
    REM4 --> ADCS
    ESC* --> ADCS
    ESC* --> SM

    BUILD --> DOCS
    BUILD -->|packages| CLI2
    GHA --> BUILD
    GHA --> T1
    GHA --> T2
    GHA --> T3
    GHA --> T4

    T1 --> ESC1
    T2 --> ESC2
    T3 --> ESC4
    T4 --> ORCH

    %% Click Events
    click CLI1 "https://github.com/computedocean/locksmith/blob/main/Invoke-Locksmith.ps1"
    click CLI2 "https://github.com/computedocean/locksmith/blob/main/Public/Invoke-Locksmith.ps1"
    click ORCH "https://github.com/computedocean/locksmith/blob/main/Locksmith.psm1"
    click ESC1 "https://github.com/computedocean/locksmith/blob/main/Private/Find-ESC1.ps1"
    click ESC2 "https://github.com/computedocean/locksmith/blob/main/Private/Find-ESC2.ps1"
    click ESC3C1 "https://github.com/computedocean/locksmith/blob/main/Private/Find-ESC3C1.ps1"
    click ESC3C2 "https://github.com/computedocean/locksmith/blob/main/Private/Find-ESC3C2.ps1"
    click ESC4 "https://github.com/computedocean/locksmith/blob/main/Private/Find-ESC4.ps1"
    click ESC5 "https://github.com/computedocean/locksmith/blob/main/Private/Find-ESC5.ps1"
    click ESC6 "https://github.com/computedocean/locksmith/blob/main/Private/Find-ESC6.ps1"
    click ESC8 "https://github.com/computedocean/locksmith/blob/main/Private/Find-ESC8.ps1"
    click ESC9 "https://github.com/computedocean/locksmith/blob/main/Private/Find-ESC9.ps1"
    click ESC11 "https://github.com/computedocean/locksmith/blob/main/Private/Find-ESC11.ps1"
    click ESC13 "https://github.com/computedocean/locksmith/blob/main/Private/Find-ESC13.ps1"
    click ESC15 "https://github.com/computedocean/locksmith/blob/main/Private/Find-ESC15.ps1"
    click AUDIT "https://github.com/computedocean/locksmith/blob/main/Private/Find-AuditingIssue.ps1"
    click REM1 "https://github.com/computedocean/locksmith/blob/main/Private/Update-ESC1Remediation.ps1"
    click REM4 "https://github.com/computedocean/locksmith/blob/main/Private/Update-ESC4Remediation.ps1"
    click HELP "https://github.com/computedocean/locksmith/blob/main/Private/Format-Result.ps1"
    click CSVUTIL "https://github.com/computedocean/locksmith/blob/main/Private/New-OutputPath.ps1"
    click COUT "https://github.com/computedocean/locksmith/blob/main/Private/Write-HostColorized.ps1"
    click ORCH "https://github.com/computedocean/locksmith/blob/main/Private/Invoke-Scans.ps1"
    click ORCH "https://github.com/computedocean/locksmith/blob/main/Private/Invoke-Remediation.ps1"
    click CLI2 "https://github.com/computedocean/locksmith/blob/main/Locksmith.psd1"
    click CLI2 "https://github.com/computedocean/locksmith/blob/main/Locksmith.psm1"
    click BUILD "https://github.com/computedocean/locksmith/blob/main/Build/Build-Module.ps1"
    click GHA "https://github.com/computedocean/locksmith/blob/main/.github/workflows/powershell.yml"
    click GHA "https://github.com/computedocean/locksmith/blob/main/.github/workflows/Deploy MkDocs.yml"
    click GHA "https://github.com/computedocean/locksmith/blob/main/.github/workflows/Create External Help.yml"
    click DOCS "https://github.com/computedocean/locksmith/blob/main/mkdocs.yml"
    click DOCS "https://github.com/computedocean/locksmith/tree/main/Docs/"
    click DOCS "https://github.com/computedocean/locksmith/blob/main/en-US/Locksmith-help.xml"
    click T1 "https://github.com/computedocean/locksmith/blob/main/Tests/Compare-ADObjects.ps1"
    click T2 "https://github.com/computedocean/locksmith/blob/main/Tests/Invoke-TSS.ps1"
    click T3 "https://github.com/computedocean/locksmith/blob/main/Tests/Show-ADObjectChanges.ps1"
    click T4 "https://github.com/computedocean/locksmith/blob/main/Tests/TSS Specs.md"

    %% Styles
    classDef runtime fill:#cfe2f3,stroke:#6fa8dc
    classDef external fill:#f4cccc,stroke:#e06666
    classDef devops fill:#d9ead3,stroke:#93c47d
    classDef data fill:#fff2cc,stroke:#ffd966
```
