Introduction

Agents in 5.2.0 are for Windows machines you have difficulties auditing.

An agent (piece of software) is installed on the machine and "checks in" with the server each day. The server will determine when the last time the agent checked-in and (usually) instruct the agent to download the latest audit script, audit itself and send the result. No more discovery issues for these machines!

Traditionally Open-AudIT has done everything it can to avoid installing anything on the target machines, but it is increasingly clear that Windows machines (in particular) are becoming more and more difficult to reliably talk to from an external machine (our Open-AudIT server). Hence we have finally relented and created the Agents feature. It is optional and discovery will continue to work as it always has - agentless. Initially agents are for Windows machines only, but down the track depending on demand, we may create agents for Linux and MacOS as well.

To install the Agent requires Administrative Privileges. To download the agent, simply go to http://YOUR_SERVER/open-audit/index.php/agents/windows/download. That will provide the generic Windows Agent. If your user(s) have Admin rights, on the bottom of the Agents List page there are commands they can run using Command Prompt (Open As Administrator) to download and install. Copy, paste, done. Obviously if you have existing management software on machines, you can use these commands (or variations of) to deploy the agents automatically.

NOTE - As at 5.2.0 the agent audit script (audit_windows.ps1) does not retrieve the database and web server items that audit_windows.vbs does. This will be coming ASAP.

NOTE - IIS and SQL are now available in 5.2.2.

How Does it Work?

The Agent will install itself to c:\Program Files\Open-AudIT Agent. It will appear in the Add/Remove Programs list (and can be uninstalled from there).

Each day at 10am (+/- 30 minutes) the agent will check-in with the server for actions to take. By default the server determines when the last time the device was audited and if greater than 24 hours, instructs the agent to download a fresh audit script, run it and submit the result.

The standard actions an agent can take are: audit, update, uninstall. An update will automatically occur if the Agent version is behind the server version.

These actions will only occur if the conditions (also in the agent definition) are met. All conditions must be met for actions to occur. If a condition is empty, it need not match. The conditions tested are: minutes since last seen, device is in subnet, device OS Family. The default Agent entry only tests for minutes > 1300 (yes, there are 1440 minutes in a day, but we allow for +/- 30 minutes and some extra).

Advanced

Warning - Here Be Dragons. If you do not specifically require this advanced feature do not enable it.

Agents also have the ability to download a file and execute a command. As you can imagine, the potential risk for misuse here is large, hence we have disabled this out of the box. To enable it you must do two things - enable it in the configuration by setting "feature_agents_advanced" to y and be using https with Open-AudIT using a globally recognized certificate authority (so the Windows client will accept it). If you set the config and use https, you will see these options appear on the Agents read page.

The only way we have come up with someone being able to abuse this is for them to commandeer your DNS and point the FQDN (or hostname, whatever your Agent is using for the URL) of your normal Open-AudIT server to their "bad" server. Their server could then instruct the Agent to download anything and run any command. HTTPS should negate this (as the host in the URL and certificate won't match) and is why we require it.

That is the scary stuff out of the way. It's simple - 99.9% of users will not need this functionality so it's not an issue. If you do require it, it is there - just use it bearing in mind these warnings.

The attribute to download a file needs to be a URL.

The attribute to run a command must be able to be run by powershell.

But Which Executes When?

The order of execution is:

Download File (assuming this is enabled)
Execute Command (assuming this is enabled)
Audit
Uninstall
Update

When an agent check in using the generic URL, the order of agent entries checked is determined by the 'weight' attribute of each individual agent entry.

Being More Specific

One more option is the ability to match on the tests and assign the agent (or more accurately the device being audited) to an Organisation and/or Location in Open-AudIT.

For example - you might give the Agent specific URL to all those in the finance department and configure it so that their machines all automatically assign themselves to the Finance Location. Or you might be an MSP and give Agent specific URLs to separate customers, which assigns their devices to different Orgs.

When you use a specific Agent URL, the server will test only that specific Agents tests, not all agents tests.

When you use the generic Agent URL, the server will test all agent entries and assign actions to a list to be performed (assuming a match).

An example of a specific Agents URL uses the ID of the agent entry instead of 'windows', so http://YOUR_SERVER/open-audit/index.php/agents/1/download instead of http://YOUR_SERVER/open-audit/index.php/agents/windows/download

I think that makes sense!

Database Schema

The database schema can be found in the application is the user has database::read permission by going to menu: Admin -> Database -> List Tables, then clicking on the details button for the table.

API / Web Access

You can access the collection using the normal Open-AudIT JSON based API. Just like any other collection. Please see The Open-AudIT API documentation for further details.