Contexts
Contexts are the ability to provide additional metadata, or contextual information, around the raw telemetry collected by the FortiInsight platform.
User Contexts
User contexts provide additional information around the user fields that FortiInsight collects, such as Job Title, Manager, Groups, Simple Display Names and Office. This information is gathered by the FortiInsight LDAP client, from your Directory Service - such as Microsoft Active Directory.
The FortiInsight LDAP Client, downloaded via the FortiInsight UI, is a self-contained application, which can be placed, and scheduled, in your environment to query the required information from your Directory Service deployment and push this valuable information up to the FortiInsight platform - providing additional contextual information around the user for the analyst to use - within Policy Settings, general Threat Hunting or for enhanced Anomaly Detection via the AI settings.
Collecting the Information
First, you will need to download and shedule the FortiInsight LDAP Client, from the UI, to run against your Directory Service.
Prerequisites
- A Windows Management server, virtual machine, with a supported OS (Windows 10 or similar)
- The Management Server must have network access to both the Directory Service, and the FortiInsight Platform API.
- A read-only, least privilege user for the LDAP client to authenticate with the Directory Service
- A FortiInsight API key (client id, and client secret).
Downloading the latest FortiInsight LDAP Client
You download FortiInsight LDAP client software from the FortiInsight UI:
- Go to Contexts > User.
- Click Download LDAP Client.
- Click Download on Run on Windows.
Running the FortiInsight LDAP Client on Windows
The FortiInsight LDAP client is a self-contained command-line application, this means that it does not require installation into the OS of choice, you can choose to either run the software ad-hoc or schedule it to create a scheduled task in order to keep the User Context information up to date with your Directory Service.
After downloading the LDAP Client package, extract it to your local management server, and update its configuration file with the required information.
All keys are stored in a configuration file, for example:
{
"ApplicationConfig": {
"LdapConnectionSettings": {
"Host": "ldap.server.com",
"Port": 636,
"Username": "ldap_username",
"Password": "ldap_password",
"EnableSSL": true,
"TrustInvalidServerCertificate": false
},
"FinsApiSettings": {
"ApiUri": "https://example.fortiinsight.cloud",
"ClientId": "client_id",
"ClientSecret": "client_secret"
}
}
}
|
Key |
Description |
|---|---|
|
ApplicationConfig.LdapConnectionSettings |
Container for all setting related to your LDAP server. |
|
Host |
IP or DNS name for the ldap host. |
|
Port |
LDAP host destination port that accepts LDAP traffic. MS Active Directory uses port 636 for encrypted traffic, and port 389 for plain text by default. Depending on the server settings, this port can be TCP/IP or UDP. |
|
Username |
is a user with least permissions to access ldap server. This user requires read only permissions to query ldap server for users and groups information |
|
Password |
Plain text password to access LDAP server. Note this will be encrypted, on disk, after a successful connection has been established. This password is required in plain text, as it will be used to authenticate with the server. |
|
EnableSSL |
Enable this to use standard ldap encryption. The port for encrypted traffic is usually different to the port of plain text traffic |
|
TrustInvalidServerCertificate |
When using an encrypted connection, it is possible to trust a server’s certificate, even when the current host machine does NOT trust it. This is analogous to a self-signed certificate on the web server. Please use with caution as this allows for trivial MITM attacks on the connection. It is recommended to ensure the server certificate is trusted by this host, and setting this value to false in production. |
|
ApplicationConfig.FinsApiSettings |
Container for all settings related to the FortiInsight Cloud Service |
|
ApiUri |
The base URL to the FortiInsight Cloud Service, |
|
ClientId |
Client ID recovered by creating a new API Key from the FortiInsight UI: Admin > Accounts > New API Key. The downloaded file will contain both the client id and the client secret. |
|
ClientSecret |
Client secret to provide authentication with the FortiInsight Cloud Service. |
Example complete configuration file:
{
"ApplicationConfig": {
"LdapConnectionSettings": {
"Host": "10.1.1.1",
"Port": 636,
"Username": "test-query-user",
"Password": "k*x9P*A4...",
"EnableSSL": true,
"TrustInvalidServerCertificate": false
},
"FinsApiSettings": {
"ApiUri": "https://org1.fortiinsight.cloud",
"ClientId": "Aj2s4oLq...",
"ClientSecret": "CXC4tpVP9cb5..."
}
}
}
Once the configuration file has been created and edited with your values, it’s time to test the connection, in a command prompt run the following:
cd %fins_download_dir%
fins.ldap.exe
Check the output for any errors. If you get any errors, most likely some configuration value is not valid or network traffic cannot flow freely to the destination hosts. Once the application finishes running with exit code 0 (success) it means that all the user information and group information has been successfully uploaded to FINS and is available in the user context.
If the application has finished running successfully, it’s time to configure a scheduled task for hands off syncing.
|
Fins LDAP Client will first test the connection to the provided LDAP server and the FortiInsight Cloud Service. If the connection is successful, the application will encrypt the configuration file, in place. Example encrypted configuration file will look like this: {"CipherText":"AQAAANCMnd8B...=="} After encryption has taken place by the application, the file can no longer be edited, the FortiInsight LDAP Client also provides a `appsettings.json.bac` file, to allow you to recreate the settings should you need to make any changes. |
FortiInsight LDAP Client Permissions
During task scheduling, fins ldap client will attempt to grant the required Access Control Permissions for the FINS LDAP Client Folder, for the NT AUTHORITY\\NETWORK SERVICE account. This is needed for Windows task scheduler as the FINS synchronization task runs under this account.
You can check these permissions manually.
When running under Windows task scheduler, ldap client is executed under Network Service account. This allows the task to run when no interactive user is logged on to the machine. Because of this Network Service account requires Full Control of the folder.
Please note that these permissions are absent by default if you download the client into the default user download folder.
The error message in Windows task scheduler will contain error code 2147942405 (0x80070005), which corresponds to unauthorised access error.
FortiInsight LDAP Client Options
The FortiInsight LDAP Client has a simple command-line interface to allow you to run, create a scheduled task, or remove the scheduled task.
Run executable, pull info from ldap server and send data to FINS API. Check appsettings.json for connection settings.
Fins.Ldap.exe
Fins.Ldap.exe run
Create a scheduled task in a Windows task scheduler. Possible `day` values: mon, tue, wed, thu, fri, sat, sun, all.
Possible `time` is a 24 hour local time in HH:mm format, for example 14:30. You can combine several values using a `SPACE` and wrap the values in `quote marks`.
This command schedules a Windows scheduled task to run on Mondays, Wednesdays and Saturdays, twice on each day at 3AM and 2:30PM
Fins.Ldap.exe scheduled --day "mon wed sat" --time "03:00 14:30"
This command schedules a Windows scheduled task to run daily at 1AM
Fins.Ldap.exe schedule -d all -t 01:00
Unschedule, removes FortiInsight ldap sync scheduled task
Fins.Ldap.exe unschedule
Other commands
Fins.Ldap.exe help
Fins.Ldap.exe version