Windows installation

Browser extensions are sandboxed and cannot access the local operating system. To allow Citadel to write to the system log it is necessary to set up Native Messaging. This involves placing a JSON manifest file that gives the path to the program that will be started by Chrome, and then receive the events and log them to the Windows Event log. The Citadel service receives those events and writes them to a syslog-formatted log file.

You can use your MDM to distribute the installer, which takes care of all of that.

On top of the Citadel installer, you need to install osquery on the endpoint, so that the agent can query the device state.

Alternatively, should you need for some reason to install Citadel manually:

  1. copy the contents of /bin/build/win to C:\Program Files\Citadel\
  2. copy the contents of /bin/controls to C:\Program Files\Citadel\controls (making sure they are not world-writable)
  3. set the following keys to C:\Program Files\Citadel\citadel.browser.agent.json:
    • HKLM\SOFTWARE\Google\Chrome\NativeMessagingHosts\citadel.browser.agent
    • HKLM\SOFTWARE\Mozilla\NativeMessagingHosts\citadel.browser-firefox.agent (note Firefox specific manifest)
    • HKLM\SOFTWARE\Opera Software\NativeMessagingHosts\citadel.browser.agent
    • HKLM\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\citadel.browser.agent
    • HKLM\SOFTWARE\BraveSoftware\Brave\NativeMessagingHosts\citadel.browser.agent
  4. run CitadelSvc.exe install to install the service.

The commands accepted by the service are:

  • CitadelSvc.exe install
  • CitadelSvc.exe uninstall
  • CitadelSvc.exe start
  • CitadelSvc.exe stop (optionally with --force)

You can verify that events are being created by checking C:\Program Files\Citadel\logs\CitadelSvc.out.log.

configuration

Citadel has sensible defaults, but you can change the configuration of Citadel, for example to change the logging and masking levels or to declare your own blacklist or local IT support e-mail address. Just place a file called citadel-browser-agent.json with the correct format in the Citadel directory. See the configuration reference for more information.