Connect Active Directory (Local Connector)

HARVEN never connects to your domain. A signed collector, installed on a server of your own, reads the directory over LDAPS and pushes a nightly snapshot out to HARVEN. Nothing is ever opened inbound.

For the general flow of adding a source, see Connect Data Sources.

Prerequisites

• A domain-joined Windows member server — never a domain controller — with PowerShell 5.1 or later

• An elevated PowerShell console for the install: it grants a logon right and registers a scheduled task

• A read-only directory account for the task; a gMSA is recommended and is proven end to end

• Outbound HTTPS/443 to HARVEN and outbound LDAPS/636 to a domain controller. No inbound rule, at any point

• This server trusting the root that issued your domain controllers' LDAPS certificates — an AD-integrated CA delivers it by group policy, any other root has to be imported by hand

• The server's clock in sync with the domain: drift makes Kerberos fail with what reads like a wrong password

Setup

Step 1 — Prepare the server and the task account

Install on a member server, not on a domain controller. The collector reads the directory and writes nothing to it, and its scheduled task runs without elevation.

A group managed service account (gMSA) is the recommended identity: it has no password for anyone to manage. Three things are needed on the domain, all of them required:

• A KDS root key exists in the forest (Add-KdsRootKey).

• This server's computer account is in the gMSA's PrincipalsAllowedToRetrieveManagedPassword — the gate most often missed.

• Install-ADServiceAccount has been run on this server, and Test-ADServiceAccount returns True.

The account also needs Log on as a batch job. The installer grants it, and denies interactive and remote-interactive logon, which this account has no business holding.

⚠️ "Do not store password" cannot be used. That logon carries no network credentials at all: the bind to the domain controller fails outright, and the stored credential cannot be decrypted either. A domain account whose password Task Scheduler keeps is the supported fallback.

Network

Outbound HTTPS/443 to three hostnames, all under your HARVEN domain: api., dbapi. and auth.

Outbound LDAPS/636 to a domain controller is a requirement, not a recommendation: a Windows Server 2025 domain controller left at its defaults refuses plain LDAP/389, and refuses LDAPS without channel binding. There is no unencrypted fallback.

This server must also trust the root that issued that certificate: the LDAPS chain is checked against the Windows certificate store. An AD-integrated CA delivers it by group policy; otherwise the root has to reach LocalMachine\Root.

No inbound rule is needed, at any point. The collector only ever calls out.

Behind a proxy, pass -ProxyUrl, or leave the machine-wide HTTPS_PROXY and NO_PROXY in place — which keeps an authenticating proxy's password out of any file of ours. Where TLS is intercepted, pass -CaBundle with the enterprise root in PEM. That setting covers HARVEN's own endpoints only: it has no bearing on the LDAPS chain to your domain controller. There is no option to skip certificate verification.

Keep the server in time sync with the domain. Kerberos tolerates about five minutes of drift, and past that the failure reads as an authentication problem rather than a clock one.

Step 2 — Download the archive on that server, and verify it

Download the archive from this page, on the server itself: the link is signed and expires within minutes, so fetch it there rather than forwarding it.

Get-FileHash — checks the SHA-256 of the archive against the hash shown here, before unpacking it.

Get-AuthenticodeSignature — checks the signature of the binary and of the three scripts. It is the stronger of the two: a hash says the download is intact, only the signature says whose it is.

diagnose.ps1, shipped in the archive, answers both of those before anything is installed: it finds the domain controllers, tries 636 and says whether this machine can build a chain for the certificate they present. It needs no credential and no install.

Step 3 — Get the enrolment code

1. Save the source so that it exists on the HARVEN side

2. Click Generate a code

3. Copy it straight away: it is shown once, expires in 24 h and can be used once

Step 4 — Run the installer, paste the code

In an elevated PowerShell console, from the directory you unpacked:

.\install.ps1 -Account 'CONTOSO\svc-harven$' -Source ad

Paste the enrolment code when it is asked for. It is prompted for and never passed as an argument, which would leave it in the PowerShell history file on disk.

The installer writes the configuration, locks the install directory down, grants the logon right, enrols this connector and registers a nightly task at 02:00 with up to 15 minutes of random delay.

It ends with a dry run that reads the directory and then opens a push to HARVEN before abandoning it, so the credential, the proxy and the encoding are all seen to work before you leave the server. Re-running it is safe; add -SkipEnroll to upgrade without spending a new code.

Step 5 — Confirm the first collection

Trigger the task by hand to collect now, or wait for the nightly run. The panel prints the Start-ScheduledTask command for it.

The history in the Tables tab shows the status, the row count per table and the age of the snapshot. A source that stops collecting is flagged there.

Fields to fill in HARVEN

Collected data

• ad_users — Domain accounts: state, password age, effective privilege: Dormant accounts, overdue passwords, standing privilege (enabled, password_age_days, is_privileged), Replicated with up to ~14 days of lag: never an exact last-seen date (last_logon_timestamp)

• ad_computers — Domain-joined machines: operating system, last logon, account age: The join key to EDR and MDM inventories (dns_hostname, operating_system)

• ad_groups — Domain groups, with the well-known privileged ones flagged: Filter on the SID rather than the name, which can be renamed (is_privileged, group_category)

• ad_group_memberships — Membership edges, flattened, with nesting expanded: Effective privilege in one join (is_nested, privileged_group)

• ad_password_policies — Default domain policy and fine-grained password settings objects: The threshold password_age_days is measured against (max_password_age_days)

• ad_domain — Domain identity, functional level and trusts

What we collect, and what we never ask for

The six tables above, and nothing else. The attribute list is fixed in the collector when it is built rather than discovered on your directory, so it is a list your security review can read in full. It never includes:

• LAPS local administrator passwords, in both the legacy and the Windows LAPS form

• gMSA managed passwords

• Password hashes and password history, in any of the attributes that hold them

• BitLocker recovery passwords and key packages

• The description and info fields on users, computers and groups — administrators routinely park service-account passwords in them

These are refused by the collector itself, not only by your ACLs: they are never requested, and a run that saw one come back stops. The audit log left on your server holds counts, identifiers and outcomes — never a row it read.

Operating it

• Everything the collector owns lives under %ProgramData%\Harven\Collector: the configuration, one directory per connector, and the logs.

• The audit log is JSON Lines, one file per connector per day, kept 30 days. It holds no directory contents and no secrets.

• Run summaries also go to the Windows Event Log under the source Harven Local Connector, with stable event ids — 1000 started, 1001 committed, 1002 committed with warnings, 1003 failed, 1010 enrolled — so a SIEM rule can be built on them.

• The scheduled tasks sit under \Harven\ in Task Scheduler, one per connector. Get-ScheduledTaskInfo gives the last result, which Task Scheduler itself shows in hexadecimal and explains nowhere.

• To stop collecting, disable the task. That is entirely your call and needs nothing from us.

• When something needs support, run diagnose.ps1: one redacted zip, read-only, sent by nobody but you, and listing its own contents so you can check it before it leaves.

Recovery after a restore or a re-image

The stored credential is bound to this machine, so a restored, re-imaged or cloned server cannot decrypt it and has to enrol again: generate a fresh code on this page and re-run the installer without -SkipEnroll. Restoring a backup of the install directory onto another machine does not carry the credential over — the collector says so rather than failing quietly.

Troubleshooting

The task history shows a number and nothing else, so the number carries the category on its own. harven-collector help prints the same table.

Removing it

• uninstall.ps1 -Connector <name> removes that connector's scheduled task, its profile and its credential. -All removes the binary, the configuration, every credential and the Event Log source; -KeepLogs keeps the audit log.

• Two things are deliberately left behind: the account's user-rights assignments, which may predate this install and may be relied on by something else, and the connector in HARVEN.

• Tell us. Uninstalling here destroys the local credential but revokes nothing — delete the connector on this page, or turn its collector off, so the identity is revoked on our side.

Official documentation

• Group Managed Service Accounts (gMSA)

• Log on as a batch job

Need help? Contact [email protected].