Development Guide

Version: 1.1.0 Last Updated: 2025-01-05

Complete guide for building, testing, and contributing to the Compliance Toolkit.

---

Table of Contents

1. Getting Started
2. Building the Project
3. Project Structure
4. Development Workflow
5. Testing
6. Contributing

---

Getting Started

Prerequisites

Required: - Go 1.24.0 or later - Windows OS (for registry access) - Git

Optional: - VS Code with Go extension - GoLand IDE - Windows Terminal

Clone Repository

git clone https://github.com/yourorg/compliance-toolkit.git
cd compliance-toolkit

Install Dependencies

go mod download

The project uses minimal dependencies: - golang.org/x/sys/windows/registry - Windows registry access - Go standard library (embed, html/template, log/slog, etc.)

---

Building the Project

Quick Build

# Build for current platform
go build -o ComplianceToolkit.exe ./cmd/toolkit.go

Build with Version Info

# Build with version and build info
go build -ldflags="-X main.Version=1.1.0 -X main.BuildDate=$(date -u +%Y-%m-%d)" -o ComplianceToolkit.exe ./cmd/toolkit.go

Build for Release

# Build optimized release binary
go build -ldflags="-s -w" -o ComplianceToolkit.exe ./cmd/toolkit.go

Flags explained: - -s - Omit symbol table - -w - Omit DWARF symbol table - Result: Smaller binary size

Clean Build

# Clean build cache and rebuild
go clean -cache
go build -o ComplianceToolkit.exe ./cmd/toolkit.go

Verify Build

# Check binary info
ComplianceToolkit.exe -h

# List available reports
ComplianceToolkit.exe -list

---

Project Structure

Directory Layout

compliance-toolkit/
├── cmd/
│   └── toolkit.go              # Main entry point
├── pkg/
│   ├── registry.go             # Registry reader core
│   ├── config.go               # Configuration loader
│   ├── htmlreport.go           # HTML report generator
│   ├── menu.go                 # Interactive menu
│   ├── evidence.go             # Evidence logging
│   ├── templatedata.go         # Template data structures
│   └── templates/              # Embedded templates
│       ├── html/               # HTML templates
│       │   ├── base.html
│       │   └── components/
│       │       ├── header.html
│       │       ├── kpi-cards.html
│       │       ├── chart.html
│       │       └── data-table.html
│       └── css/                # CSS templates
│           ├── main.css
│           └── print.css
├── configs/
│   └── reports/                # Report configurations
│       ├── NIST_800_171_compliance.json
│       ├── fips_140_2_compliance.json
│       ├── system_info.json
│       ├── software_inventory.json
│       ├── network_config.json
│       ├── user_settings.json
│       └── performance_diagnostics.json
├── output/
│   ├── reports/                # Generated HTML reports
│   ├── evidence/               # Evidence JSON logs
│   └── logs/                   # Application logs
├── examples/                   # Example scripts
│   ├── scheduled_compliance_scan.ps1
│   └── scheduled_compliance_scan.bat
├── docs/                       # Documentation
│   ├── README.md
│   ├── user-guide/
│   ├── developer-guide/
│   ├── reference/
│   └── PROJECT_STATUS.md
├── go.mod                      # Go module definition
├── go.sum                      # Dependency checksums
└── README.md                   # Project README

Core Components

Component	File	Purpose
Registry Reader	pkg/registry.go	Windows registry operations
Config Loader	pkg/config.go	JSON report configuration
HTML Reporter	pkg/htmlreport.go	HTML report generation
Evidence Logger	pkg/evidence.go	Compliance evidence logging
Menu System	pkg/menu.go	Interactive CLI menu
Main Application	cmd/toolkit.go	Entry point and orchestration

---

Development Workflow

1. Make Code Changes

Edit files in pkg/ or cmd/:

# Edit registry reader
notepad pkg/registry.go

# Edit report template
notepad pkg/templates/html/components/header.html

# Edit CSS
notepad pkg/templates/css/main.css

2. Build and Test

# Quick build
go build -o ComplianceToolkit.exe ./cmd/toolkit.go

# Run with test report
ComplianceToolkit.exe -report=system_info.json

# Check output
start output\reports\

3. Verify Changes

For code changes:

# Run tests
go test ./pkg/...

# Run with verbose output
go test -v ./pkg/...

# Check coverage
go test -cover ./pkg/...

For template changes: 1. Build: go build -o ComplianceToolkit.exe ./cmd/toolkit.go 2. Generate report 3. Open in browser 4. Check changes

4. Format Code

# Format all Go files
go fmt ./...

# Or use gofmt directly
gofmt -w .

5. Lint Code

# Install golangci-lint (one time)
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Run linter
golangci-lint run

---

Testing

Run Tests

All tests:

go test ./pkg/...

Specific package:

go test ./pkg -v

With coverage:

go test -cover ./pkg/...

Generate coverage report:

go test -coverprofile=coverage.out ./pkg/...
go tool cover -html=coverage.out

Test Structure

Tests are located alongside source files:

pkg/
├── registry.go
├── registry_test.go           # Registry reader tests
├── config.go
├── config_test.go             # Config loader tests
├── htmlreport.go
└── htmlreport_test.go         # HTML report tests

Writing Tests

Example test:

package pkg_test

import (
    "context"
    "testing"

    "compliancetoolkit/pkg"
    "golang.org/x/sys/windows/registry"
)

func TestReadString(t *testing.T) {
    reader := pkg.NewRegistryReader()
    ctx := context.Background()

    // Read a known value
    value, err := reader.ReadString(
        ctx,
        registry.LOCAL_MACHINE,
        `SOFTWARE\Microsoft\Windows NT\CurrentVersion`,
        "ProductName",
    )

    if err != nil {
        t.Fatalf("ReadString failed: %v", err)
    }

    if value == "" {
        t.Error("Expected non-empty ProductName")
    }
}

Integration Tests

Run integration tests:

# Run all tests including integration
go test -tags=integration ./pkg/...

Example integration test:

//go:build integration
// +build integration

package pkg_test

import (
    "context"
    "testing"

    "compliancetoolkit/pkg"
)

func TestFullReportGeneration(t *testing.T) {
    // Load config
    config, err := pkg.LoadReportConfig("../configs/reports/system_info.json")
    if err != nil {
        t.Fatalf("Failed to load config: %v", err)
    }

    // Execute report
    report := pkg.NewHTMLReport(config.Metadata.ReportTitle, "./test_output")
    // ... execute queries ...

    // Generate report
    err = report.Generate()
    if err != nil {
        t.Fatalf("Failed to generate report: %v", err)
    }
}

---

Contributing

Development Guidelines

1. Code Style
2. Follow Go standard formatting (go fmt)
3. Use meaningful variable names
4. Add comments for exported functions

5. Keep functions focused and small

6. Error Handling

7. Always check and handle errors
8. Provide context in error messages

9. Use custom error types when appropriate

10. Logging

11. Use structured logging (log/slog)
12. Include operation context

13. Log at appropriate levels (Debug, Info, Warn, Error)

14. Testing

15. Write tests for new features
16. Maintain >80% code coverage

17. Include both unit and integration tests

18. Documentation

19. Update docs for new features
20. Add code comments for complex logic
21. Include examples in documentation

Adding a New Feature

Example: Adding a new report type

1. Create report configuration:

// configs/reports/my_new_report.json
{
  "version": "1.0",
  "metadata": {
    "report_title": "My New Report",
    "report_version": "1.0.0",
    "author": "Your Name",
    "description": "Description of report",
    "category": "Category",
    "last_updated": "2025-01-05"
  },
  "queries": [
    {
      "name": "my_check",
      "description": "My Check Description",
      "root_key": "HKLM",
      "path": "SOFTWARE\\...",
      "value_name": "MyValue",
      "operation": "read"
    }
  ]
}

1. Test the report:

# Build
go build -o ComplianceToolkit.exe ./cmd/toolkit.go

# Run
ComplianceToolkit.exe -report=my_new_report.json

# Verify output
start output\reports\

1. Update documentation:

// docs/reference/REPORTS.md
### My New Report

**File:** `my_new_report.json`
**Category:** Category
**Description:** Description of report
...

1. Create pull request

Pull Request Process

1. Fork the repository

2. Create a feature branch: bash git checkout -b feature/my-new-feature

3. Make your changes:

4. Add code
5. Add tests

6. Update docs

7. Test your changes: bash go test ./pkg/... go build -o ComplianceToolkit.exe ./cmd/toolkit.go # Manual testing

8. Commit with clear message: bash git add . git commit -m "Add new feature: description"

9. Push to your fork: bash git push origin feature/my-new-feature

10. Open pull request

11. Describe changes
12. Link related issues
13. Request review

Code Review Checklist

Before submitting:

• [ ] Code follows Go standards (go fmt)
• [ ] Tests pass (go test ./pkg/...)
• [ ] Coverage maintained (>80%)
• [ ] Documentation updated
• [ ] Examples added if needed
• [ ] No breaking changes (or documented)
• [ ] Commit messages are clear
• [ ] Build succeeds (go build)

---

Build Automation

Makefile (Optional)

Create Makefile for common tasks:

.PHONY: build test clean fmt lint

build:
    go build -o ComplianceToolkit.exe ./cmd/toolkit.go

test:
    go test -v ./pkg/...

coverage:
    go test -coverprofile=coverage.out ./pkg/...
    go tool cover -html=coverage.out

clean:
    go clean -cache
    rm -f ComplianceToolkit.exe coverage.out

fmt:
    go fmt ./...

lint:
    golangci-lint run

release:
    go build -ldflags="-s -w" -o ComplianceToolkit.exe ./cmd/toolkit.go

install:
    go install ./cmd/toolkit.go

Usage:

make build
make test
make coverage

PowerShell Build Script

Create build.ps1:

# build.ps1 - Build automation script

param(
    [switch]$Release,
    [switch]$Test,
    [switch]$Clean
)

if ($Clean) {
    Write-Host "Cleaning build cache..." -ForegroundColor Cyan
    go clean -cache
    Remove-Item -Path "ComplianceToolkit.exe" -ErrorAction SilentlyContinue
}

if ($Test) {
    Write-Host "Running tests..." -ForegroundColor Cyan
    go test -v ./pkg/...
    if ($LASTEXITCODE -ne 0) {
        Write-Error "Tests failed!"
        exit 1
    }
}

Write-Host "Building ComplianceToolkit..." -ForegroundColor Cyan

if ($Release) {
    # Release build with optimizations
    go build -ldflags="-s -w" -o ComplianceToolkit.exe ./cmd/toolkit.go
} else {
    # Development build
    go build -o ComplianceToolkit.exe ./cmd/toolkit.go
}

if ($LASTEXITCODE -eq 0) {
    Write-Host "Build successful!" -ForegroundColor Green
    Write-Host "Binary: ComplianceToolkit.exe" -ForegroundColor Cyan
} else {
    Write-Error "Build failed!"
    exit 1
}

Usage:

# Development build
.\build.ps1

# With tests
.\build.ps1 -Test

# Release build
.\build.ps1 -Release

# Clean and build
.\build.ps1 -Clean

---

Debugging

VS Code Configuration

Create .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch Toolkit",
            "type": "go",
            "request": "launch",
            "mode": "debug",
            "program": "${workspaceFolder}/cmd/toolkit.go",
            "args": []
        },
        {
            "name": "Launch with Report",
            "type": "go",
            "request": "launch",
            "mode": "debug",
            "program": "${workspaceFolder}/cmd/toolkit.go",
            "args": ["-report=system_info.json", "-quiet"]
        }
    ]
}

Debugging Tips

1. Add debug logging: go slog.Debug("Debug info", "key", value)

2. Use delve debugger: bash dlv debug ./cmd/toolkit.go

3. Print variables: go fmt.Printf("DEBUG: variable = %+v\n", variable)

4. Check logs: bash type output\logs\toolkit_*.log

---

Performance Optimization

Profiling

CPU profiling:

import "runtime/pprof"

f, _ := os.Create("cpu.prof")
pprof.StartCPUProfile(f)
defer pprof.StopCPUProfile()

Memory profiling:

import "runtime/pprof"

f, _ := os.Create("mem.prof")
pprof.WriteHeapProfile(f)
f.Close()

Analyze:

go tool pprof cpu.prof
go tool pprof mem.prof

Benchmarking

func BenchmarkReadString(b *testing.B) {
    reader := pkg.NewRegistryReader()
    ctx := context.Background()

    for i := 0; i < b.N; i++ {
        _, _ = reader.ReadString(
            ctx,
            registry.LOCAL_MACHINE,
            `SOFTWARE\Microsoft\Windows NT\CurrentVersion`,
            "ProductName",
        )
    }
}

Run:

go test -bench=. ./pkg/...

---

Troubleshooting

Build Issues

Issue: cannot find package

Solution:

go mod tidy
go mod download

Issue: templates not found

Solution:

# Verify templates exist
ls pkg/templates/html/*.html
ls pkg/templates/css/*.css

# Rebuild
go clean -cache
go build -o ComplianceToolkit.exe ./cmd/toolkit.go

Runtime Issues

Issue: Access denied errors

Solution:

# Run as Administrator
Right-click ComplianceToolkit.exe → Run as administrator

Issue: Templates not updating

Solution:

# Clean build cache
go clean -cache
go build -o ComplianceToolkit.exe ./cmd/toolkit.go

---

Next Steps

• ✅ Add Reports: See Adding Reports Guide
• ✅ Customize Templates: See Template System
• ✅ Architecture: See Architecture Overview
• ✅ Project Status: See Project Status

---

Development Guide v1.0 ComplianceToolkit v1.1.0 Last Updated: 2025-01-05