FleetDM-PowerShell

PowerShell module for FleetDM API integration

View the Project on GitHub jorgeasaurus/FleetDM-PowerShell

FleetDM-PowerShell

FleetDM-PowerShell Logo

A lightweight PowerShell module for interacting with the FleetDM Free Tier REST API.

CI/CD Pipeline Documentation PowerShell Gallery Version PowerShell Gallery Downloads PowerShell Platforms GitHub Release License: MIT

Overview

FleetDM-PowerShell provides a native PowerShell interface to FleetDM Free Tier, enabling administrators to manage hosts, queries, policies, and software inventory through familiar PowerShell cmdlets. This module focuses on FleetDM’s free functionality without requiring Premium licenses or external dependencies.

Download Statistics

Download Statistics

📚 View Full Documentation - Comprehensive online documentation with detailed cmdlet reference

Features

Requirements

Installation

Install-Module -Name FleetDM-PowerShell -Force

From Source

# Clone the repository
git clone https://github.com/Jorgeasaurus/FleetDM-PowerShell.git
cd FleetDM-PowerShell

# Import directly without building
Import-Module ./FleetDM-PowerShell.psd1 -Force

Quick Start

Connect to FleetDM

# Using API token (recommended - most secure)
$token = ConvertTo-SecureString "your-api-token-here" -AsPlainText -Force
Connect-FleetDM -BaseUri "https://fleet.example.com" -ApiToken $token

# Using username/password
$cred = Get-Credential
Connect-FleetDM -BaseUri "https://fleet.example.com" -Credential $cred

Basic Operations

# Get all hosts
Get-FleetHost

# Get specific host
Get-FleetHost -Id 123

# Filter hosts by status
Get-FleetHost -Status online

# Run a live query and get results directly
$results = Invoke-FleetQuery -Query "SELECT * FROM system_info;" -HostId 1,2,3
$results.Results | Format-Table

# Or use a saved query
$results = Invoke-FleetSavedQuery -QueryId 123 -HostId 1,2,3

# Get policies
Get-FleetPolicy

# Get software inventory
Get-FleetSoftware -VulnerableOnly

Available Cmdlets

For detailed help and examples, visit the Online Documentation or use Get-Help <cmdlet-name> -Full.

Connection Management

Host Management

Query Management

Policy Management

Software Management

Advanced

Examples

Example 1: Find and Remove Offline Hosts

# Find hosts offline for more than 30 days
$offlineHosts = Get-FleetHost -Status offline | 
    Where-Object { $_.seen_time -lt (Get-Date).AddDays(-30) }

# Remove them (with confirmation)
$offlineHosts | Remove-FleetHost -Confirm

Example 2: Check Policy Compliance

# Get all policies with low compliance
Get-FleetPolicy | 
    Where-Object { $_.compliance_percentage -lt 80 } |
    Format-Table name, compliance_percentage, failing_host_count

Example 3: Find Vulnerable Software

# Get all software with critical vulnerabilities
Get-FleetSoftware -VulnerableOnly | 
    Where-Object { $_.highest_severity -eq 'critical' } |
    Sort-Object hosts_count -Descending |
    Select-Object name, version, hosts_count, cve_count

Example 4: Run Query on Specific Platform

# Get Ubuntu hosts and run a query
$ubuntuHosts = Get-FleetHost | Where-Object { $_.platform -eq 'ubuntu' }
$results = Invoke-FleetQuery -Query "SELECT * FROM os_version;" -HostId $ubuntuHosts.id

# View the results
$results.Results | ForEach-Object {
    Write-Host "Host: $($_.HostId)"
    $_.Rows | Format-Table
}

Example 5: Create macOS Security Policy

# Create a policy to check FileVault auto-login is disabled on macOS
New-FleetPolicy -Name "FileVault Auto-Login Disabled" `
    -Query "SELECT 1 FROM managed_policies WHERE domain = 'com.apple.loginwindow' AND name = 'DisableFDEAutoLogin' AND value = 1 LIMIT 1;" `
    -Platform darwin

Example 6: Bulk Policy Creation

# Import policies from CSV
Import-Csv policies.csv | ForEach-Object {
    New-FleetPolicy -Name $_.Name -Query $_.Query -Description $_.Description
}

Pipeline Support

All cmdlets support pipeline operations:

# Chain operations - get online Windows hosts
Get-FleetHost -Status online | 
    Where-Object { $_.platform -eq 'ubuntu' } |
    Select-Object id, hostname, seen_time

# Execute query on filtered hosts
$hostIds = Get-FleetHost | 
    Where-Object { $_.platform -eq 'debian' } |
    Select-Object -First 5 -ExpandProperty id
Invoke-FleetQuery -Query "SELECT * FROM system_info;" -HostId $hostIds

# Or pipe host IDs directly as an array
@(17,6,8) | Invoke-FleetQuery -Query "SELECT * FROM os_version;"

Error Handling

The module provides detailed error messages and supports standard PowerShell error handling:

try {
    Get-FleetHost -Id 99999
}
catch {
    Write-Error "Failed to get host: $_"
}

Authentication

The most secure method is using API tokens:

  1. Generate an API token in FleetDM UI (Account → Get API Token)
  2. For API-only users: fleetctl user create --api-only
  3. Store token securely using SecureString
  4. Tokens don’t expire unless explicitly revoked
# Store token securely
$token = Read-Host "Enter API Token" -AsSecureString
Connect-FleetDM -BaseUri "https://fleet.example.com" -ApiToken $token

Username/Password

Less secure but available when tokens aren’t accessible:

$cred = Get-Credential
Connect-FleetDM -BaseUri "https://fleet.example.com" -Credential $cred

Security Best Practices

  1. Never hardcode tokens in scripts or source control
  2. Use SecureString for token storage
  3. Create API-only users for automation (requires admin access)
  4. Rotate tokens regularly
  5. Use least-privilege principles for API users

Development

For developers who want to contribute or modify the module:

# Clone the repository
git clone https://github.com/Jorgeasaurus/FleetDM-PowerShell.git
cd FleetDM-PowerShell

# Import the module directly from source
Import-Module ./FleetDM-PowerShell.psd1 -Force

# Make your changes and test them

Testing

Run the Pester tests:

# Run all tests
Invoke-Pester

# Run specific test file
Invoke-Pester -Path .\Tests\Get-FleetHost.Tests.ps1

# Run with code coverage
Invoke-Pester -CodeCoverage @('Public\*.ps1', 'Private\*.ps1')

Limitations

Troubleshooting

Connection Issues

# Test connection
Test-NetConnection -ComputerName fleet.example.com -Port 443

# Enable verbose output
Connect-FleetDM -BaseUri "https://fleet.example.com" -ApiToken $token -Verbose

SSL/TLS Issues

# For self-signed certificates (not recommended for production)
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}

Module Import Issues

# Force reload module
Remove-Module FleetDM-PowerShell -Force -ErrorAction SilentlyContinue
Import-Module FleetDM-PowerShell -Force -Verbose

# Or import directly from source
Import-Module ./FleetDM-PowerShell.psd1 -Force

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Development Guidelines

CI/CD Pipeline

The project uses GitHub Actions for continuous integration:

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Acknowledgments

Documentation

Support

Version History

1.0.0 - Initial Release

Roadmap