PowerShell Module

The Athena PowerShell module wraps the same JWT-authenticated REST API the console uses, so you can automate your fleet from scripts. Connect once with Connect-Athena, then drive agents, deployments, commands, collections, packages, scheduled jobs, users, PKI and more with over a hundred cmdlets.

Import the module#

Copy the module folder onto a management host and import it. The manifest declares a minimum of PowerShell 5.1, so no extra runtime is required on a current Windows box.

# Import by path…
Import-Module .\Athena\Athena.psd1

# …or by name, once the folder is on $env:PSModulePath
Import-Module Athena

# Confirm it loaded and list the cmdlets
Get-Command -Module Athena

Connect & authenticate#

Connect-Athena establishes an authenticated session and stores it in a module-level variable that every other cmdlet reuses. Connections are HTTPS only; pass the bare hostname (no protocol) and, if needed, a port. The default port is 8443. The authenticating provider — Local, Ldap or Keycloak — is surfaced on the returned session (its AuthProvider) and in the “Connected” message.

Supported providers#

Connect-Athena supports two login flows, which map to the three providers the server accepts:

With the username/password flow you do not choose Local versus Ldap yourself — you supply a credential (or accept the prompt) and the server authenticates it against the appropriate provider, then reports which one on the session.

Username / password (Local & LDAP)#

# Default: HTTPS on port 8443, prompts for credentials (Local/LDAP)
Connect-Athena -Server "athena.contoso.com"

# Custom port
Connect-Athena -Server "athena.contoso.com" -Port 443

# Non-interactive with a stored credential
$cred = Get-Credential -UserName "admin"
Connect-Athena -Server "athena.contoso.com" -Credential $cred

# Return the session object instead of just storing it
$session = Connect-Athena -Server "athena.contoso.com" -PassThru
$session.AuthProvider   # Local or Ldap

Keycloak SSO (device-code flow)#

Add -Keycloak to sign in through Keycloak using the OIDC device-code grant. This flow is browserless on the console side: Connect-Athena requests a device and user code from the Keycloak realm, prints a verification URL and user code for you to approve in a browser, then polls for the token and exchanges it at the server for an Athena session. The three Keycloak parameters are operator-supplied — there is no anonymous server endpoint that hands them out.

# Keycloak SSO: approve the shown user code in a browser, then the CLI gets a session
Connect-Athena -Server "athena.contoso.com" -Keycloak `
    -Issuer "https://kc.contoso.com/realms/athena" `
    -ClientId "athena-cli"

The session that comes back is byte-identical in shape to a password login — a JWT bearer token reused by every other cmdlet — with its AuthProvider set to Keycloak.

Parameters#

Connect-Athena takes these parameters. -Credential belongs to the default (username/password) parameter set; -Keycloak, -Issuer and -ClientId belong to the Keycloak set and are all required together.

Inspect or end the session with the other two session cmdlets. Disconnect-Athena calls api/auth/logout, which revokes the session token on the server (see Signing out) and records the sign-out in the audit log. It then clears the stored session. If the session has already expired, the cmdlet skips the server call and only clears the stored session.

# See the current session, including its expiry
Get-AthenaSession

# Log out and clear the cached token
Disconnect-Athena

Server certificate validation#

From module version 2.15.0, the module checks the Athena server’s TLS certificate before it sends your password or API token. Earlier versions accepted any certificate. Check which version you have with (Get-Module Athena).Version.

A server certificate is accepted in either of these cases:

• This computer already trusts it. Examples are a certificate from your enterprise CA, or the Athena CA installed in the machine’s trusted root store. The certificate must also list the host name you passed to -Server.
• It is a server certificate from the Athena CA pinned for that server. This is the normal case for Athena’s default self-signed certificate. A pinned CA belongs to one Athena install, so the certificate is accepted under any name or IP address, including one the certificate does not list. For example, you can connect to an appliance by its IP address. The certificate must be valid for server authentication. An agent’s client certificate from the same CA is never accepted as the server.

First connection: pin on first use#

The first time you connect to a server whose certificate this computer does not trust, the module:

1. downloads the server’s public Athena CA from the anonymous endpoint GET /api/pki/ca/download?format=cer. No credentials are sent on this request.
2. checks that the certificate the server presented chains to that CA.
3. saves (pins) the CA for your user and that server, and prints a yellow warning with the CA’s SHA-256 fingerprint and the location of the pin file.

WARNING: First connection to https://athena.contoso.com:8443: its certificate is not trusted by this
computer, so its Athena CA is now pinned for this user. CA SHA-256 fingerprint: 3A:9F:…:C2. Verify it on
the server: Get-FileHash -Algorithm SHA256 on its CA certificate in DER (.cer) form gives the same hex
without colons. If it does not match, delete '…\trusted-servers\athena.contoso.com_8443.cer' and do not
use this connection.

After the first connection, every cmdlet in the session checks the certificate silently. If a later certificate does not chain to the pinned CA, the connection is refused.

Verify the fingerprint#

Compare the fingerprint in the warning with the server’s real CA. Get the CA in DER (.cer) form over a path you trust. You can download it in the console under Settings → Security → Certificate, or from a computer that already trusts the server. Then hash it:

# On a computer you trust: save the CA in DER form and hash it
Save-AthenaCACertificate -Server "athena.contoso.com" -Path .\athena-ca.cer -Format cer
Get-FileHash .\athena-ca.cer -Algorithm SHA256

# The Hash value is the fingerprint without the colons

If the values do not match, delete the pin file named in the warning and do not use that connection.

Where pins are stored#

Pins are stored per user and per server address and port. Each one is a DER-encoded .cer file named <host>_<port>.cer:

The address is part of the file name, so athena.contoso.com and the server’s IP address get separate pins. The first connection to each one pins it as described above. A different Windows user, or a service account running a scheduled script, has its own pin folder. Run one interactive connection as that account first, or copy a verified .cer into its folder under the expected file name.

When a certificate is refused#

Connect-Athena stops before it sends any credential. The error message tells you why:

If you replace Athena’s self-signed certificate with one your computers already trust, you do not need to do anything else. The trusted certificate is accepted (with the host-name check) even when a pin exists.

Lab use: -SkipCertificateCheck#

-SkipCertificateCheck turns validation off. It prints a warning and pins nothing:

• On Connect-Athena, the setting is kept on the session. Every later cmdlet in that session, including Disconnect-Athena, also skips the check. With -Keycloak, it also skips validation of the Keycloak certificate.
• Get-AthenaHealth, Get-AthenaCACertificate, Get-AthenaCACertificateInfo and Save-AthenaCACertificate can run without a session when you pass -Server. Each of them has its own -SkipCertificateCheck switch. Without it, the same pin-on-first-use rules apply. When these cmdlets run on an existing session, they use that session’s setting.

Keycloak sign-in (-Keycloak) validates the Keycloak server’s certificate only against the computer’s trusted root store. It does not pin. Install the CA that issued Keycloak’s certificate on the management host, or use -SkipCertificateCheck in a lab.

Command browser#

Every cmdlet in the module, side by side with its reference. Pick a command in the list on the left — filter by name, synopsis or -Parameter and narrow by category — and its syntax, description, parameters and examples appear on the right. This index is generated from the module source; for the authoritative, version-specific set on your own server run Get-Command -Module Athena.

Common tasks#

Find agents and filter the fleet

Get-AthenaAgent supports lookup by -Id or -Hostname, filtering by -Tag, -Status (Online, Offline, Pending, Maintenance) or a free-text -Search, and -All to page through the whole estate.

# Only the online agents
Get-AthenaAgent -Status Online

# Everything with a given tag, exported to CSV
Get-AthenaAgent -Tag "production" | Export-Csv agents.csv

# A single agent by hostname
Get-AthenaAgent -Hostname "SERVER01"

Run a command across targets

Invoke-AthenaCommand queues a remote command to agents selected by -TargetAgentIds or -TargetTags, and accepts agents straight off the pipeline. The -Type is one of PowerShell (default), Batch, Shell, Executable, Python or Chocolatey, and -TimeoutSeconds defaults to 300.

# Pipe production agents into a command
Get-AthenaAgent -Tag "production" |
  Invoke-AthenaCommand -Command "Get-Service -Name Spooler"

# A longer batch job with an explicit timeout
Invoke-AthenaCommand -Command "maintenance.bat" -Type Batch `
  -TimeoutSeconds 600 -TargetTags "web-server"

Query the audit log

# Login failures from the last 7 days, all pages, to CSV
Get-AthenaAudit -EventType "LoginFailure" `
  -FromDate (Get-Date).AddDays(-7) -All |
  Export-Csv login-failures.csv

Scripted health check

Get-AthenaHealth works without a session — pass it a -Server directly — which makes it convenient for unattended monitoring.

$health = Get-AthenaHealth -Server "athena.contoso.com"
if ($health.OverallStatus -ne "healthy") {
    Write-Warning "Athena is $($health.OverallStatus)"
}

Roles & permissions#

The module calls the same endpoints as the console, so a token's role decides which cmdlets succeed. Calls outside your role are rejected by the server. As a rule of thumb:

• Helpdesk and up — read-oriented queries such as Get-AthenaAgent, Get-AthenaAudit and inventory cmdlets.
• Operator — operational actions like Invoke-AthenaCommand and running deployments.
• Admin — sensitive management such as PKI operations, user management and server settings.

See Roles & Permissions for the full role matrix. Check your own role with (Get-AthenaCurrentUser).Role.