BIOS Configuration

Athena shows the BIOS / UEFI settings of your Windows machines. You do not need to install a vendor tool or go to each machine. The Windows agent reads every attribute from the vendor's built-in firmware provider on HP, Dell (2018 and newer) and Lenovo business hardware. It records the current value, the legal values and the vendor's flags, plus which BIOS passwords are set. The server combines these reports into a model catalog that lists the settings each hardware model offers. You can then define BIOS baselines: the values you want for chosen settings on a vendor and model. Athena shows which machines have drifted from them, and an Admin can remediate a drifted machine: send it the baseline's values, which take effect at its next restart. An Admin can also set, change or remove the BIOS administrator password on one machine or many. Athena records which stored credential holds each machine's current password. Everything runs between your Athena server and its agents, so it works on an air-gapped network.

Where it appears#

• Policies → BIOS (/policies/bios): a status bar, then a switch between the Model catalog and the Baselines table. The address /policies/bios?view=baselines opens the Baselines table directly. The Policies landing page also has a BIOS card. It shows the number of Models and of agents that are Reporting or Not supported.
• BIOS compliance (/policies/bios/compliance): the fleet drift view. It has no menu entry of its own. Open it with Fleet compliance → on the status bar, the Baselines table or an agent's BIOS section.
• Agent details → BIOS: one machine's settings, as the agent last read them, compared with the baseline that applies to it.

Permissions

Without bios.view, the Policies entry, the landing card and the agent section are hidden, and the REST endpoints return 403. With bios.view but without bios.baselines.manage, the Baselines table and editor are read only. The editor shows "Read only: managing baselines needs the Manage BIOS baselines permission." Both permissions need the BIOS module licence. Without bios.remediate, the Remediate button is not shown. See Permission Model and the remediation permissions.

When settings are read#

The server asks a Windows agent for a new read in three cases:

The agent allows 120 seconds for a read. If it takes longer, the agent reports "The BIOS read timed out." Offline agents are not asked. They are read on their next check-in. A normal read does not write an audit log entry, because a machine can have a couple of hundred settings every day.

You can change the daily sweep in appsettings.json (or with the matching environment variables):

For example, the environment variable Modules__Bios__Refresh__MaxAgeHours=12 keeps reports at most about half a day old. See Configuration. The 1-hour check-in limit is fixed.

Agent details → BIOS#

The BIOS section of a Windows agent is in one of four states:

Firmware card

• Vendor, with the vendor's WMI provider underneath.
• Model: for example HP ProBook x360 435 G7. When a baseline applies, the line Matched by <model match> shows which model match selected it.
• BIOS version.
• Collected at: when the agent's report arrived, with the number of attributes by type (for example 212 attributes · 180 enumeration · 12 integer · 20 string).
• BIOS password: Not set, or N of M set, followed by each password the vendor exposes, marked set or not set. Lenovo reports PowerOn, Supervisor, HardDisk and SystemManagement. HP and Dell report the names their firmware uses. Only whether a password is set is reported. The password itself is never read.

Applied baseline card

When an enabled baseline applies to the machine, the Applied baseline card names it (a link to the baseline) and says which read it was evaluated against. Chips count the managed attributes: N drifted, N compliant and N not applicable. Fleet compliance → opens the fleet view. When the machine has drifted and you hold bios.remediate, a Remediate button sits beside the chips (see Remediating drift). After a remediation, a Last remediation card shows the result per attribute. When no baseline applies, the Attributes card says "No enabled baseline matches this vendor and model, so nothing is evaluated." with a Baselines → link.

The settings table

When a baseline applies, drifted rows come first, then not-applicable, compliant and unmanaged rows. If the baseline manages an attribute this firmware does not have, the table still shows it as a Not applicable row with the note "Not in this firmware's attributes (<model>, BIOS <version>): not applicable, never drift."

Use Search attributes or values to filter by attribute name, menu path or current value. The Group list filters by the first part of the vendor's menu path. When a baseline applies, a State list filters by row state. The counter shows how many rows match and how many attributes the agent reported. The Collect now button sends a read request. The section updates by itself when the answer arrives, usually within seconds. If the agent cannot be asked, a message tells you why:

Values the agent withholds

Some firmware, HP in particular, shows secrets as plain text settings: upload-server passwords, access and signing keys, and the OEM product key. The agent never sends the value of a text or ordered-list setting whose name contains password, passphrase, secret, key/keys, digital marker or username. These rows show Withheld by the agent. List and number settings are never withheld, because their values come from the vendor's published choices and ranges. The agent's own log records only the vendor and the number of settings, never a value.

Policies → BIOS: the model catalog#

The BIOS Configuration page starts with a status bar: Drift evaluation on, the number of baselines, the number of models catalogued, Last evaluated with a time, and Fleet compliance →. Below it, a switch selects Model catalog or Baselines. The page updates by itself when an agent reports or a baseline changes.

The Model catalog is built from the reports. Each vendor and model that reports gets its own list of settings, with the vendor's exact attribute names and legal values. Use it to see which settings each model offers before you plan a change. The model table shows:

Click the model name or the view button (Show this model's attributes) to open a model. No model opens by itself. The detail has a model picker and lists each Attribute (with its menu path), its Type (Enumeration, String, Integer, OrderedList), Legal values, Flags and Last seen. You can search by attribute name, legal value or path.

A setting that has been missing from the model's newest report for 30 days is marked stale, because a BIOS update can rename or remove a setting. Stale settings are shown, not hidden. Machines without a vendor provider never appear in the catalog. They count as Not supported.

Baselines#

A baseline lists the values you want for chosen BIOS settings on one vendor's hardware. It uses the firmware's own attribute names and values, taken from the model catalog. Athena does not translate settings between vendors: the same feature has a different name on HP, Dell and Lenovo, so each baseline is for one vendor and a model match.

A baseline is desired state only. Saving, turning on or off, or deleting it re-checks drift on the server from the values agents already reported. Nothing is sent to any machine, and no BIOS setting is changed.

The Baselines table

Open Policies → BIOS and choose Baselines. Each row shows:

With bios.baselines.manage, the table has a New baseline button and, on each row, Edit baseline and Delete baseline. Delete asks for confirmation: "Delete this baseline and its desired values? Its agents stop being evaluated against it. Nothing is written to any machine." Without the permission, each row has a View baseline button.

Creating or editing a baseline

1. In the Baselines view, click New baseline. The editor opens at /policies/bios/baselines/new. An existing baseline opens at /policies/bios/baselines/<id>.
2. In the Baseline card, enter a Name, choose a Vendor (HP, Dell, Lenovo, or another vendor your fleet has reported), and enter the Model match (see below). Add a Description if you want, and leave Baseline enabled on. "Disabled baselines are not evaluated."
3. Check the hint under the model match. It shows how many reporting agents and which catalogued models the match covers. If it covers none, it warns "Matches 0 agents - this looks exactly like full compliance." and may suggest a match, for example "The fleet reports HP ProBook x360 435 G7; did you mean HP ProBook*?"
4. Click Edit attributes to open Advanced - raw attributes. This lists every attribute of one catalogued model of the vendor (pick the model at the top). Tick an attribute to manage it, then choose its desired value. List settings offer only their legal values. Numbers are limited to the reported range, and text to the reported length. A ticked attribute starts with the value most of that model's agents report, if that value is legal. Use the search box and Managed only to find attributes, then click Done.
5. Back in the editor, the Managed attributes table shows each attribute's Desired value, Legal values and Fleet value: the most common value that model's agents report now, how many agents report it, and how many other values exist.
6. Save. The toast says "Baseline saved. Drift re-evaluated; nothing was written to any machine."

Changing the vendor clears the attributes you picked, because one vendor's attribute names mean nothing on another vendor's hardware. If the vendor has no catalog yet, the editor says so: the catalog fills itself the first time an agent of that vendor reports.

Model match

• An exact model string, for example HP ProBook x360 435 G7. Case does not matter.
• Or a prefix that ends in one *, for example HP ProBook*. A * anywhere else is refused. * on its own covers every model of the vendor.
• Only one baseline governs a machine. If several enabled baselines of the same vendor match, the most specific one wins: an exact match beats any wildcard, and a longer prefix beats a shorter one. If two are equally specific, the one whose name comes first alphabetically wins. A baseline that loses to a more specific one governs 0 agents, and the table shows Matches 0 agents.

What a baseline may contain

The editor, the REST API and every other client use the same rules. A save is refused with a message when:

The rules use the current catalog. If a BIOS update changes a model's legal values, a saved baseline can fail its own rules the next time it is saved, and that includes turning it on or off. The message names the attribute to fix.

How drift is decided#

Drift is worked out on the server each time a page, the API or a monitor reads it. Athena compares the values each agent last reported with the current baselines. No result is stored, so a saved baseline applies the moment anyone looks, and an old result can never be shown. Agents need no update for baselines.

Each managed attribute gets one state:

Each agent gets one compliance state:

BIOS compliance (fleet view)#

Fleet compliance → opens BIOS compliance. It covers every agent that has sent a BIOS read. Windows agents that never reported, and Linux and macOS agents, are not listed. The page updates by itself when an agent reports or a baseline changes. Edit baselines returns to the Baselines table.

• Four figures: Compliant (with N% of evaluated agents), Drifted, Unknown and Not supported. The percentage is compliant ÷ (compliant + drifted). Unknown, Not supported and agents with no baseline are left out, so the figure moves only when a real machine changes. A note gives the number of reporting agents that have no baseline.
• By model: one row per vendor and model, with the Baseline that governs it (or Not evaluated when no enabled baseline matches), Agents, a Distribution bar, and the Compliant, Drifted, Unknown and Not supp. counts. Models with drift come first, then the models with the most agents.
• Drifted agents: select a model row (or Show drifted agents) to list its drifted machines. Each row shows the agent, BIOS version, Drifted settings (current → desired) and Collected at, with a Collect now button to read the machine again after you fix it. With bios.remediate, each row also has a Remediate button.

Remediating drift#

Remediate sends one drifted machine the desired values of its governing baseline. The Windows agent writes them through the vendor's firmware interface: HP's BIOS setting interface, Dell's BIOS attribute interface, or Lenovo's set-and-save BIOS settings interface. The firmware queues the new values, and they take effect at the machine's next restart. Athena does not restart the machine for you. Plan the restart yourself, for example with an agent restart or the user's next reboot.

• Only drifted attributes are sent. Compliant and not-applicable attributes are left alone. You cannot pick a subset: the remediation is the machine's whole drift against its baseline.
• One machine at a time. There is no fleet-wide or scheduled remediation, and saving a baseline still writes nothing. Each remediation is a deliberate action by an Admin, and it is audited.
• Online machines only. An offline agent is not queued. You get "The agent is not connected. Nothing was sent." Try again when it is online.
• Agent version. Writing BIOS settings needs Windows agent 1.2.121 or later. Update older agents first with agent updates.

Remediating a machine

1. Open the machine's Agent details → BIOS section and find the Remediate button beside the drift chips on the Applied baseline card. Or open BIOS compliance, select a model and use the Remediate button on a drifted agent's row. Its tooltip reads "Remediate: write this machine's drifted attributes".
2. The Remediate BIOS settings dialog lists what will be written, for example "Writes 2 drifted attributes of baseline 'ProBook fleet - Secure Boot' to PC-5CG1013QPH:", with each attribute as current → desired.
3. Under BIOS password, choose the stored credential that holds the machine's BIOS setup password, or No BIOS password set for a machine without one (see BIOS passwords). If Athena holds a confirmed escrowed administrator password for the machine, that credential is selected for you. Otherwise No BIOS password set is selected. The Firmware card shows whether the machine has a BIOS password set.
4. Click Remediate. On success the toast reads "Sent 2 attributes to PC-5CG1013QPH. They take effect at the next restart."
5. Restart the machine. The agent reads its BIOS again when it checks in after the restart, and the Last remediation card and the drift update.

If nothing was sent, the toast says why:

Safety rules on the machine

Before it writes anything, the agent reads the BIOS again and checks each attribute:

• Secure Boot is never disabled remotely. A value that would turn Secure Boot off is skipped with "Secure Boot cannot be disabled remotely; it needs physical presence at the machine." Turning Secure Boot on is allowed.
• BitLocker is suspended for one restart when a write touches a boot or security attribute (Secure Boot, boot options, TPM, legacy/CSM, UEFI and similar, judged by the attribute name and its menu path). This prevents a BitLocker recovery-key prompt at the restart. If BitLocker protection is off there is nothing to suspend. If BitLocker cannot be suspended, or its state cannot be read, nothing is written and every attribute fails with "BitLocker could not be suspended for the restart, so nothing was written (a boot or security change would prompt for the recovery key)."
• Read-only attributes are skipped ("Read-only on this firmware."). An attribute that already has the desired value is reported as Applied ("Already set.").
• An attribute the firmware does not have fails with "Not an attribute of this machine's firmware." A name or value containing a double quote is refused.
• On Lenovo, the settings are saved together at the end. If the save fails, every setting fails with "Set, but SaveBiosSettings failed: …", because an unsaved setting changes nothing.
• The agent allows 300 seconds for a remediation. If it takes longer it reports "The BIOS apply timed out; restart and re-read before trusting any value."

BIOS passwords

If the machine has a BIOS setup password, the firmware rejects writes without it. Athena takes the password from the encrypted credential store at the moment of the send. It goes only to that one agent, over its encrypted connection. It is never stored in a baseline, a log or the audit trail. The audit trail records only the credential's name.

• A typed password (all vendors). On the Credentials page, click New Credential and set Type to Secret. A Secret has no username: enter a name and put the BIOS password in Password. Every active Secret credential is offered in the dialog's BIOS password list, sorted by name. Logon credentials (Local Account, Domain) are never offered.
• An HP password file (HP only). If your HP machines use an encrypted password file made with HP's HPQPswd tool, use Add an HP password file (.bin) in the dialog: type a Credential name, then choose the .bin file. It is stored encrypted as a Secret credential (description "HP BIOS password file (HPQPswd .bin)") and selected for you. The file may be at most 16 KB. The machine needs HP BIOS Configuration Utility (BiosConfigUtility64.exe) installed in its default folder, HP\BIOS Configuration Utility under Program Files or Program Files (x86). Athena does not ship it. A password file sent to a Dell or Lenovo machine fails with "A password file is an HP format; this machine is <vendor>."

Permissions for remediation

The built-in Admin role has all of these. Operator and Helpdesk cannot remediate. To let another group remediate, give a custom role these permissions. Every permission is checked again when you click Remediate.

The Last remediation card

The agent's BIOS section keeps the latest remediation of that machine. A new one replaces it. The card's subtitle reads "Baseline '<name>' · sent by <user> at <time>", and the table lists each attribute with its Desired value, its Result and a Detail (the agent's message and the vendor's return code).

While any attribute is Pending restart, the server asks the agent for a new BIOS read on every check-in, not only once an hour. A restart shows up as a reconnect, so the read after it turns Pending restart into Verified and updates drift. When an attribute is Applied at once, the server asks for a new read straight away.

Common firmware answers in the Detail column:

BIOS administrator password#

An Admin can set, change or remove the BIOS administrator password of a Windows machine from Athena. The agent uses the vendor's built-in firmware interface, so nothing is installed on the machine. The new and current passwords are Secret credentials in the credential store. Athena reads them when it sends the request and passes them only to that agent, over its encrypted connection. They are never written to a log or the audit trail. For each machine, Athena also escrows which credential holds the current administrator password. Later password changes and remediations use that credential by default.

• Supported hardware. HP, Dell (2018 and newer) and Lenovo, the same machines whose BIOS Athena can read. The machine must have reported a BIOS read (it is not Not supported).
• Which password. HP's Setup Password, Dell's Admin password and Lenovo's Supervisor password. Other BIOS passwords (power-on, hard disk) are not changed.
• Lenovo cannot set a first password. Lenovo's firmware interface can only change or remove an existing supervisor password. On a Lenovo machine with no supervisor password, set it once in BIOS setup at the machine. After that, Athena can change or remove it. Lenovo passwords sent from Athena cannot contain a comma, a semicolon or a non-ASCII character.
• Plain passwords only. An HP password file (.bin) can be used for remediation, but not to set or remove a password.
• Online machines only. An offline agent is not queued. You get "The agent is not connected. Nothing was sent."
• Agent version. Needs Windows agent 1.2.144 or later.

Setting or changing the password

1. Create the new password as a Secret credential: Credentials → New Credential, Type Secret, a name, and the password (see BIOS passwords).
2. Open the dialog:
   • One machine: in Agent details → BIOS, the BIOS administrator password card has a key button with the tooltip "Set, change or remove the BIOS administrator password".
   • Many machines: in BIOS compliance, select one of the Compliant, Drifted or Unknown figures to list those agents. Tick the agents (or the header box for all), then click Set BIOS password. The Not supported list has no selection.
3. In the BIOS administrator password dialog, choose an Action: Set or change, or Remove.
4. For Set or change, pick the New password credential.
5. Choose the Current password:
   • Escrowed: <name> (the default) uses the machine's confirmed escrowed credential. When nothing is escrowed it reads "Escrowed (nothing escrowed: none set)", and Athena treats the machine as having no password. For many machines it reads "Each agent's escrowed password (none escrowed: none set)": each machine uses its own escrow.
   • None set: the machine has no administrator password now.
   • A Secret credential: the password the machine has now, if it is not the escrowed one.
6. Read the warning and click Set password or Remove password. The toast reads "Sent to <host>. The escrow moves when the agent confirms." For many machines it reads "Sent to N agents. Each answers with its own verified result.", or "Sent to N of M agents. Not sent: …" with a count for each reason.

The change does not need a restart. When the agent answers, the server asks it for a new BIOS read, so the Firmware card's BIOS password line updates straight away. Without credentials.use, the dialog shows "Changing a BIOS password needs the 'Use stored credentials' permission." and cannot send.

If nothing was sent, the toast (or the REST outcome) says why:

What the agent checks

• It reads the BIOS first. If the machine has an administrator password and no current password was given, nothing is sent to the firmware: "An administrator password is set and no current password was given; nothing was changed." This keeps the firmware's wrong-password counter from going up.
• If the firmware reports no administrator password, the current password is not sent. A Remove on such a machine succeeds with "No administrator password is set; there was nothing to remove."
• After the firmware accepts the change, the agent reads the "password is set" flag again. The result is Succeeded only when the flag matches the request: set for Set, not set for Remove. If the firmware said OK but the flag did not move, the result is Unverified: "The firmware accepted the change but still reports the password … Re-read after a restart before trusting either password."

The escrow card

The BIOS administrator password card on Agent details → BIOS shows "Which credential Athena holds as this machine's current administrator password." It holds the credential's name, never the password.

• Escrowed credential: the credential name and the time it was confirmed. None set (confirmed) after a successful removal. None escrowed when Athena has never confirmed one.
• Last change: the latest request, its state, "<action> by <user> at <time>", and the agent's message with the vendor code.

Only the answer to the latest request moves the escrow. A late or repeated answer to an older request is ignored.

Alerting on BIOS drift#

BIOS compliance adds four module fields that you can use in monitors, dynamic collections, tagging rules and reports. They use the same evaluation as the pages, so a machine never reads one way on its tab and another way in a monitor.

For example, a monitor on Module.bios.ComplianceState · Equals · Drifted alerts on exactly the machines whose BIOS differs from their baseline. Every field except BaselineName always has a value, including on Linux and macOS agents (NotSupported).

Audit log#

Every baseline create, update and delete writes a bios.baseline-changed event (shown as BIOS baseline changed) at Information severity. The action is Create, Update or Delete. The description names the baseline, vendor, model match, attribute count and whether it is enabled, and ends with "Nothing was written to any machine." The event details list every managed attribute with its desired value. Turning a baseline on or off is recorded as an Update. Normal BIOS reads are not audited. See Audit Event Types.

Remediation and the administrator password write four more events:

PowerShell#

The Athena PowerShell module has two read cmdlets. Run Connect-Athena first. Both need bios.view and the BIOS module licence. There are no cmdlets for baselines, compliance or remediation yet. Use the REST API for those.

# The Secure Boot related attributes of one machine
Get-AthenaAgent -Hostname PC-5CG1013QPH | Get-AthenaBiosSetting -Name '*Secure Boot*'

# Status, model and BIOS password state of one machine
Get-AthenaAgent -Hostname PC-5CG1013QPH | Get-AthenaBiosSetting -Summary

# Every model the fleet has reported, then the 2023 CA switches of one HP model
Get-AthenaBiosCatalog
Get-AthenaBiosCatalog -Vendor HP -Model 'HP ProBook x360 435 G7' -Name '*CA 2023*'

REST API#

Every route needs a bearer token (see API Reference) with bios.view, and returns 403 when the licence does not include module.bios. Responses use the standard success / data / message envelope. JSON is camelCase. Status, state and type values are sent as numbers, counted from 0 in the order listed on this page. For example, agent status is 0 NeverReported, 1 Supported, 2 NotSupported, 3 Error. The refresh outcome is 0 Sent, 1 NotLicensed, 2 NotSupported, 3 NotConnected, 4 NotFound. The setting type is 0 Enumeration, 1 String, 2 Integer, 3 OrderedList, 4 Unknown.

curl -k -X POST -H "Authorization: Bearer <token>" \
  https://athena.example.local:8443/api/agents/<agent-id>/bios-settings/refresh

Baselines and compliance

Reads need bios.view. Create, replace and delete also need bios.baselines.manage. None of these routes sends anything to an agent.

Agent compliance state: 0 Compliant, 1 Drifted, 2 Unknown, 3 NoBaseline, 4 NotSupported, 5 NotReported. Attribute state: 0 Compliant, 1 Drifted, 2 NotApplicable. A successful save returns the stored baseline with the message "Baseline saved. Drift re-evaluated; nothing was written to any machine."

curl -k -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  https://athena.example.local:8443/api/bios/baselines \
  -d '{
        "name": "ProBook fleet - Secure Boot",
        "vendor": "HP",
        "modelMatch": "HP ProBook*",
        "enabled": true,
        "settings": {
          "Configure Legacy Support and Secure Boot": "Legacy Support Disable and Secure Boot Enable"
        }
      }'

Attribute names and values must be spelled exactly as the firmware reports them. Copy them from the model catalog (GET /api/bios/catalog?vendor=HP&model=…) rather than typing them.

Remediation

All routes need bios.view. Remediating and the password routes also need bios.remediate. Unlike the routes above, outcomes here are sent as strings (for example "Sent", "PendingReboot").

curl -k -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  https://athena.example.local:8443/api/agents/<agent-id>/bios-remediate \
  -d '{ "credentialId": "<secret-credential-id>" }'

curl -k -H "Authorization: Bearer <token>" \
  https://athena.example.local:8443/api/agents/<agent-id>/bios-remediation

Administrator password

All routes need bios.view. The two POST routes also need bios.password, and credentials.use to read the passwords. Outcomes are sent as strings. A POST only sends the request. Read the agent's verified answer with the GET.

curl -k -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  https://athena.example.local:8443/api/agents/<agent-id>/bios-password \
  -d '{ "mode": "Set", "newCredentialId": "<new-secret-id>", "currentIsNone": true }'

curl -k -H "Authorization: Bearer <token>" \
  https://athena.example.local:8443/api/agents/<agent-id>/bios-password

Troubleshooting#

Related#

• Policies: the nav group that holds BIOS, BitLocker, Sysmon and Power Management.
• Credentials: storing the BIOS password as a Secret credential.
• BitLocker: the protection that is suspended for one restart during a boot or security remediation.
• Secure Boot Certificates: firmware readiness for the 2023 Secure Boot CA rollout.
• Boot & Security inventory and Hardware inventory: BIOS version, Secure Boot and TPM state for every agent.
• Licensing: separately licensed modules.
• PowerShell Module: the full cmdlet reference.