PSKB4Reporting

PSKB4Reporting is a PowerShell 7 module for the KnowBe4 Reporting API.

The module wraps KnowBe4's read-only Reporting API for account, user, group, phishing, and training data. It also uses the new API pagination with cursors instead of the URL paging.

Features

• Bearer-token authentication with Connect-KB4Reporting
• Regional API support for US, EU, CA, UK, and DE
• Read-only commands for every documented Reporting API endpoint
• Cursor-first pagination with page pagination fallback
• Normal output unwraps KnowBe4 page wrappers and returns the actual objects
• -Raw support for response metadata, headers, request IDs, and troubleshooting
• Conservative request pacing and retry handling for 429 and transient 5xx responses
• Mocked unit tests plus live integration coverage
• PSScriptAnalyzer-backed release validation

Project

• Version: 1.0.0
• Company: Genius GRC
• Author: Eric Shoemaker
• License: MIT, see LICENSE

Build Provenance

This module was built from scratch with OpenAI Codex. It started as more of a private test to see what was possible. Could I just point Codex at API documentation and have it build a module? Turns out the answer is yes! At a certain point, I decided to release it publicly along with the full transparency of the entire Codex prompt used to build it. If nothing else, it's interesting to me.

Codex was used to analyze the KnowBe4 Reporting API documentation, scaffold the repository, implement the PowerShell module, organize the public functions, create unit and live integration tests, add comment-based help, prepare release metadata, and build the release validation script.

Codex first analyzed the KnowBe4 Reporting API documentation and produced docs/API-PLAN.md as the module build plan. That plan captures the API sources, endpoint mapping, intended PowerShell command surface, implementation phases, and early design choices Codex proposed before implementation began.

The final module differed from the initial plan in a few important ways, including the package rename to PSKB4Reporting, the addition of full live integration coverage, release packaging, analyzer enforcement, and normal output unwrapping. Those differences are documented in docs/PLAN-VS-IMPLEMENTATION.md.

The full development prompt history has been published in docs/Codex Prompt Prompt History.md. That file exists so reviewers can inspect the natural-language instructions, decisions, and iteration history that shaped the module.

Layout

.
|-- Module/
|   `-- PSKB4Reporting/
|       |-- PSKB4Reporting.psd1
|       |-- PSKB4Reporting.psm1
|       |-- Private/
|       `-- Public/
|           |-- Account/
|           |-- Connect/
|           |-- Groups/
|           |-- Phishing/
|           |-- Training/
|           `-- Users/
|-- Tests/
|   |-- Integration/
|   |-- Unit/
|   `-- TestEnvironment.ps1
|-- docs/
|-- examples/
|-- build.ps1
|-- LICENSE
`-- PSScriptAnalyzerSettings.psd1

Quick Start

Create a token in the KnowBe4 Reporting API Management Console, then import and connect:

Import-Module .\Module\PSKB4Reporting\PSKB4Reporting.psd1 -Force

Connect-KB4Reporting -ApiToken $env:KB4_REPORTING_API_TOKEN -Region US
Get-KB4Account
Get-KB4User -Status Active -PageSize 100

For a simple script example, see examples/Get-ActiveUsers.ps1.

Output

By default, list commands return the objects inside KnowBe4's data wrapper:

Get-KB4User -Status Active -PageSize 2

Use -Raw when you need page metadata, headers, status code, URI, or the KnowBe4 request ID:

$response = Get-KB4User -Status Active -PageSize 2 -Raw
$response.StatusCode
$response.RequestId
$response.Body.data

Use -All to retrieve all pages:

Get-KB4User -Status Active -All -PageSize 500

Commands

Connection:

Connect-KB4Reporting
Disconnect-KB4Reporting
Get-KB4ReportingContext

Account:

Get-KB4Account
Get-KB4AccountRiskScoreHistory

Users and groups:

Get-KB4User
Get-KB4UserRiskScoreHistory
Get-KB4Group
Get-KB4GroupMember
Get-KB4GroupRiskScoreHistory

Phishing:

Get-KB4PhishingCampaign
Get-KB4PhishingSecurityTest
Get-KB4PhishingRecipient

Training:

Get-KB4TrainingStorePurchase
Get-KB4TrainingPolicy
Get-KB4TrainingCampaign
Get-KB4TrainingEnrollment

List commands support -PageSize, -Cursor, -Page, -UsePagePagination, -All, and -Raw where relevant. Cursor pagination is preferred because KnowBe4 plans to deprecate page-based pagination in July 2026.

Tests

Unit tests mock the transport layer and do not require a real KnowBe4 token:

Invoke-Pester -Path .\Tests\Unit

Live integration tests read credentials from Tests/.env:

KB4_REPORTING_API_TOKEN=
KB4_REPORTING_REGION=US

Tests/.env is ignored by Git.

Run all tests:

Invoke-Pester -Path .\Tests -PassThru

Run only the comprehensive live function coverage:

Invoke-Pester -Path .\Tests\Integration\PSKB4Reporting.AllFunctions.Live.Tests.ps1 -PassThru

Static Analysis

Install PSScriptAnalyzer before running release validation:

Install-Module PSScriptAnalyzer -Scope CurrentUser
Invoke-ScriptAnalyzer -Path .\Module\PSKB4Reporting -Settings .\PSScriptAnalyzerSettings.psd1 -Recurse

The build script runs PSScriptAnalyzer against the module, tests, examples, and the release script.

Build and Release

Run the release script from the repository root:

.\build.ps1

The script validates the module manifest, runs PSScriptAnalyzer, runs unit tests, and stages a package-ready module folder at Release\PSKB4Reporting. It also returns the Publish-Module -WhatIf command to run before publishing.

To skip static analysis or unit tests during local iteration:

.\build.ps1 -SkipAnalyzer
.\build.ps1 -SkipTests

API Sources

• KnowBe4 Reporting API docs: https://developer.knowbe4.com/rest/reporting
• OpenAPI backing document: https://developer.knowbe4.com/elvis-swagger.yml
• Reporting API overview: https://support.knowbe4.com/hc/en-us/articles/115016090908-Reporting-API-Overview
• API change log: https://support.knowbe4.com/hc/en-us/articles/37449905326995-API-Change-Log