Docs · Install

Install the DetectMonkey collector

Read exactly what gets installed before you sign up, and get unstuck in one paste if something goes wrong.

We can see, we can't touch

  • The collector only sends events out. DetectMonkey never sends it commands, and it cannot change your machine after the install.
  • Everything it changes is written below, and every change can be undone with the uninstall command.
  • Your collector key lives in an environment variable, never on a command line, so it does not show up in process lists or audit logs.

Before you start

  • Get your command from the console: API keys, then Install the collector. It already contains your key. On this page the key is shown as <your-collector-key>. Never paste a real key into a ticket, a chat or the Get help form.
  • You need administrator rights on the machine (root on Linux, an elevated PowerShell on Windows).
  • It takes about a minute per machine.

Supported platforms

  • Linux: Ubuntu 20.04 and newer, Debian 11 and newer, RHEL, Rocky Linux and AlmaLinux 8 and newer. x86_64 or aarch64, with systemd.
  • Windows: Windows 10 and 11, and Windows Server 2016 and newer. 64-bit, in PowerShell 5.1 or newer.

Other systems are refused before anything is changed (exit code 6). macOS is not supported yet.

Network requirements

  • Always: outbound HTTPS (port 443) to codein.ca. That is the install check-in and every event after it. Nothing needs to reach into the machine.
  • During the install only: github.com (the Vector release; GitHub sends the download on to its own content hosts).
  • Linux, only if missing: your distribution's package repositories, for auditd.
  • Windows, only if Sysmon is not already installed: download.sysinternals.com. The Sysmon configuration comes from codein.ca.
  • Behind a proxy, set DM_PROXY (see each platform below).

Third-party software comes from upstream

Vector (the forwarder) is downloaded straight from upstream (its own release page on github.com) and checked against a checksum built into the installer. Sysmon is downloaded from Microsoft and the installer refuses it unless it is signed by Microsoft. We never mirror either one. Only our own configuration files come from codein.ca.

Linux

Install

Run both lines in a terminal on the machine. The first sets your key for this shell only; the second runs the installer as root and passes the key through.

export DM_KEY='<your-collector-key>'
curl -fsSL https://codein.ca/install.sh | sudo --preserve-env=DM_KEY bash

What it changes

  • Downloads Vector into /opt/detectmonkey/vector, owned by root, unless a root-owned Vector at the same version is already on the machine.
  • Installs auditd (and tar) if missing, using your distribution's package manager, and makes sure auditd is enabled and running.
  • Writes our audit rules into their own file, /etc/audit/rules.d/detectmonkey.rules, and reloads them. Your own rules files are never edited.
  • Sets auditd's log_format to ENRICHED and remembers what it was before.
  • Writes the forwarder configuration (it holds your key, readable by root only) in /etc/detectmonkey, and a machine ID and an install record in /var/lib/detectmonkey.
  • Starts a systemd service called detectmonkey-vector that runs at boot.

Upgrade

Run the same install command again. It upgrades in place: same machine ID, same key.

Diagnose

Prints a short report for support. It never prints your key, only its kind and last four characters.

curl -fsSL https://codein.ca/install.sh | sudo bash -s -- --diagnose

Uninstall

Removes only what the installer added: the service, our audit rules, Vector (only if the installer put it there), and the configuration. It puts auditd's log_format back, and removes auditd only if the installer was the one that installed it.

curl -fsSL https://codein.ca/install.sh | sudo bash -s -- --uninstall

Behind a proxy

Use a plain URL with no user name or password, and pass DM_PROXY through sudo as well. It covers the install and the event stream.

export DM_KEY='<your-collector-key>'
export DM_PROXY='http://proxy.example:3128'
curl -fsSL https://codein.ca/install.sh | sudo --preserve-env=DM_KEY,DM_PROXY bash

Check that it works (Linux)

Once the install says it is connected, run one harmless command that a server should always flag. You will see a real alert in the console, so you know the whole path works.

awk 'BEGIN {system("/bin/sh &")}'
  • It makes awk start a shell, which closes straight away. It changes nothing on the machine.
  • Wait a minute or two, then open the console. Incidents (and the Alerts list) shows an alert called Suspicious Invocation of Shell via AWK - Linux. Machines shows this host with a recent event.
  • Nothing after ten minutes? Run the diagnose command above and paste the result in Get help.

Why not try useradd or a system-info command? A new Linux machine is registered as a server, and servers are tuned to show only high and critical alerts so ordinary admin commands stay quiet. That is on purpose, and it is why those commands do not alert.

Windows

Install

Open PowerShell as Administrator and paste the line. The key stays inside your own PowerShell session.

$env:DM_KEY='<your-collector-key>'; irm https://codein.ca/install.ps1 | iex

What it changes

  • Downloads Vector into C:\Program Files\DetectMonkey\Vector, with the folder locked to Administrators and SYSTEM.
  • Keeps a machine ID and an install record, C:\ProgramData\DetectMonkey\install-state.json, that lists the setting each change had before.
  • Installs Microsoft Sysinternals Sysmon with our configuration. A Sysmon that was already there keeps its own configuration unless you ask otherwise (DM_REPLACE_SYSMON_CONFIG=1).
  • Turns on the advanced audit policy subcategories the detections read (logon and special logon, credential validation and Kerberos, process creation, account and group management, scheduled tasks, policy change, file shares, service installs, security state and system integrity), for success and failure.
  • Turns on the command line in process-creation events, PowerShell script block logging and module logging, and the Task Scheduler operational log.
  • Runs the forwarder as a Windows service called DetectMonkeyCollector, which starts at boot.
  • Tells Windows to use those subcategories instead of the nine older audit categories, which then stop applying. Uninstall puts this back.
  • It never turns off logging you already have. A domain Group Policy that sets the same things wins over the settings on the machine.

Upgrade

Run the same install command again. It upgrades in place and the machine keeps its ID.

Diagnose

Prints a short report for support. It never prints your key, only its kind and last four characters. Needs PowerShell as Administrator.

$env:DM_ACTION='diagnose'; irm https://codein.ca/install.ps1 | iex

Uninstall

Removes the service, the forwarder and its configuration, and Sysmon only if the installer put it there. Audit policy and logging settings go back to what the install record says, unless someone has changed them since.

$env:DM_ACTION='uninstall'; irm https://codein.ca/install.ps1 | iex

Behind a proxy

Use a plain URL with no user name or password.

$env:DM_PROXY='http://proxy.example:3128'; $env:DM_KEY='<your-collector-key>'; irm https://codein.ca/install.ps1 | iex

DM_ACTION and DM_PROXY stay set in that PowerShell window. Open a new Administrator window, or run Remove-Item Env:DM_ACTION (and Env:DM_PROXY), before you install again, or the install command will repeat the old action.

Exit codes

The installer prints a one-line reason and stops with a code. 0 means connected (or removed, or reported). On Windows, pasted into PowerShell, the code is left in $LASTEXITCODE so your window stays open. An unexpected failure on Windows stops with code 1: paste its message and the diagnose report into Get help.

Linux

CodeWhat it meansWhat to do
2No collector key, or an option from the old installer.Copy the install command from your console again.
3The key was rejected, or is malformed.Make a new key in the console and copy the command again.
4This machine cannot reach codein.ca.Allow outbound HTTPS (port 443) to codein.ca, or set DM_PROXY.
5Not run as root (this includes the diagnose and uninstall commands).Use the two lines above with sudo --preserve-env=DM_KEY. If sudo will not keep the key, open a root shell with sudo -i, export the key there and run the curl line without sudo.
6Unsupported system, or a bad option. Nothing was changed.Check the supported list above. A proxy value must be a plain URL like http://proxy.example:3128.
7The platform answered with an error.Wait a minute and run the command again. If it repeats, paste the diagnose report into Get help.
8A download or a package install failed (Vector from github.com, or auditd from your distribution's repositories).Check outbound HTTPS to github.com and your package mirrors, then run the command again.
9The forwarder service did not start.Run journalctl -u detectmonkey-vector --no-pager -n 50 and paste the result into Get help.
10The Vector download failed its checksum. Nothing was installed.Something between you and github.com changed the file. Try again from another network or through a mirror (DM_VECTOR_BASE_URL); if it repeats, ask for help.
11Vector rejected the forwarder configuration.Paste the error line and the diagnose report into Get help.
12The platform did not confirm this machine.Run the command again. If it repeats, paste the diagnose report into Get help.

Windows

CodeWhat it meansWhat to do
2No collector key.Copy the install command from your console again.
3The key was rejected, or is malformed.Make a new key in the console and copy the command again.
4This machine cannot reach codein.ca, or the connection was closed before codein.ca answered (the installer tried 3 times).Run the command again. If it repeats, allow outbound HTTPS (port 443) to codein.ca, or set DM_PROXY.
5PowerShell was not opened as Administrator.Right-click PowerShell, choose Run as administrator, then paste the command again.
6Unsupported system or a bad option (32-bit Windows, older than Windows 10 or Server 2016, a proxy that is not a plain URL, or a protected folder that is not owned by Administrators).Nothing was changed. Fix what the message names and run the command again.
7The platform answered with an error, or did not confirm this machine.Wait a minute and run the command again. If it repeats, paste the diagnose report into Get help.
8The Vector download from github.com failed, did not match its checksum, or its folder could not be locked down.Check outbound HTTPS to github.com, then run the command again.
9The forwarder configuration did not validate, or the DetectMonkeyCollector service could not be updated.Paste the error text and the diagnose report into Get help.
10Sysmon could not be downloaded from download.sysinternals.com, or the download is not signed by Microsoft. The rest of the install still ran (audit policy, PowerShell logging, forwarder); the code is returned at the end and Sysmon is missing.Check outbound HTTPS to download.sysinternals.com. If the signature check failed, something altered the file: ask for help.
11The Sysmon configuration could not be fetched from codein.ca or applied (Sysmon 15 or newer is needed), or Sysmon could not be removed on uninstall. On install this too is reported at the end, after the rest of the install ran.Check outbound HTTPS to codein.ca, then run the command again.
12The audit policy or PowerShell logging could not be read or set. Or, on uninstall, the saved state file could not be read or a setting could not be put back (the file is kept).Read the message, fix what it names, and run the same command again.

Get help

Run the diagnose command above on the stuck machine, copy everything it prints and paste it below. It is short, it hides your key, and it tells us the system, the installer version, whether the service runs and whether the machine can reach codein.ca.

It does include the machine's host name and OS. Read it before you send it, and remove anything you do not want to share.

The form goes to our contact relay and reaches the Codein team. If you would rather write to us, use the contact page.