deploy.md

brick: Deployment

• Project README

Table of contents

• Order of deployment
• Preparation
• Building brick
• Deploying brick
  • Assumptions
  • Create service account
  • Setup output directories
  • Pre-create files
  • Log files
    • Summary
    • Deploy logrotate snippet
  • Deploy brick binary
    • Picking the right binary
    • Deploying the binary
  • Configure brick
    • Start with the template configuration file
  • Firewall rules
  • Configure and deploy systemd unit
  • Start brick now and enable it to start again at boot

Order of deployment

Technically brick can be deployed before or after fail2ban, before or after Splunk alerts are enabled and before or after EZproxy is setup to monitor a disabled users flat-file, though you'll have to touch or otherwise pre-create the files monitored for both applications.

It is easier if you go ahead and build/deploy brick first before making other changes covered by our documentation.

Preparation

Backups. While the process of deploying brick and related applications is normally non-destructive, it's a good idea to always assume the worst when making system-wide changes; installing/using fail2ban is arguably a large change.

If available to you, create a full VMware snapshot, Hyper-V checkpoint, etc. Being able to quickly undo an "oops" moment is critical for these types of changes.

Building brick

See the build instructions doc.

Deploying brick

Assumptions

Mostly for the sake of complete examples, we will assume the following:

• Remote Splunk server is at 192.168.2.2
• EZproxy server is at 192.168.10.20
• brick is deployed to the EZproxy server on port 8000
• brick generated files are saved to /var/cache/brick/
  • /var/cache/brick/users.brick-disabled.txt
• brick config files are deployed to /usr/local/etc/brick/
  • /usr/local/etc/brick/config.toml
    • originally named/found as contrib/brick/config.example.toml
  • /usr/local/etc/brick/ips.brick-ignored.txt
  • /usr/local/etc/brick/users.brick-ignored.txt
• brick user and brick group have been created
• brick runs as the brick user
• EZproxy server OS is Ubuntu Linux 16.04 or 18.04 LTS

Create service account

1. sudo useradd --system --shell /bin/false brick

Setup output directories

1. sudo mkdir -vp /usr/local/etc/brick
2. sudo mkdir -vp /var/log/brick
3. sudo chown -Rv brick:syslog /var/log/brick
4. sudo chmod -Rv u=rwX,g+rX,o= /var/log/brick
   • allow service account full access
   • allow rsyslog read-only access to directory and contents
   • deny access to all other non-root user accounts
5. sudo mkdir -vp /var/cache/brick
6. sudo chown -Rv brick:brick /var/cache/brick

Pre-create files

1. sudo touch /var/log/brick/users.brick-reported.log
   • pre-creating this file satisfies fail2ban requirements that the file exist before the associated jail is activated
2. sudo chown -v brick:brick /var/log/brick/users.brick-reported.log
   • the fail2ban daemon runs with elevated privileges and will already be able to access this file
   • we explicitly ensure that the brick application won't be blocked from modifying it
3. sudo touch /var/log/brick/syslog.log
   • our rsyslog configuration snippet directs matching log messages here
4. sudo chmod -v g+rw /var/log/brick/syslog.log
   • allow rsyslog read-write access to log file

See also the rsyslog-specific instructions in the rsyslog doc.

Log files

Summary

brick generates log output to stdout, stderr and directly to the reported users log file. systemd handles routing stdout, stderr messages, rsyslog handles fetching from systemd and everything ends up (if using the provided rsyslog configuration) in a local log file for further review (and processing by fail2ban)

Here are those log files:

• /var/log/brick.syslog.log
  • written to by rsyslog
• /var/log/brick/users.brick-reported.log
  • written to by brick

These files will continue to grow until they're rotated out, which on most Linux distros is handled by the logrotate utility. Configuring logs for rotation often involves using an existing file as template and modifying to match your specific requirements. The same holds true here. The contrib/logrotate/brick logrotate configuration snippet/file handles rotation for both log files currently generated.

See also the rsyslog-specific instructions in the rsyslog doc.

Deploy logrotate snippet

1. sudo cp -vi contrib/logrotate/brick /etc/logrotate.d/

Deploy brick binary

Picking the right binary

In addition to all of the supporting files and settings, let's not forget about deploying the actual brick executable (as an earlier version of these docs did).

Depending on your target environment, you'll either need the 32-bit or 64-bit version of the binary that you generated earlier by following the build instructions.

Alternatively, you can also obtain precompiled binaries for the latest release.

After downloading the binaries you should decompress each of them (e.g., xz -d brick-linux-amd64.xz).

If you see this uname -m output	Use the filename with this pattern	Your EZProxy server has this architecture
x86_64	brick-linux-amd64	64-bit
i686	brick-linux-386	32-bit

For example, if you run uname -m on your EZproxy server and get x86_64 as the output, you will want to deploy the brick-linux-amd64 binary.

Deploying the binary

NOTE:

• If downloading precompiled binaries for the latest release make sure to decompress each of them (e.g., xz -d brick-linux-amd64.xz) before deploying them.
• If you opt to deploy brick using the provided DEB or RPM packages then binaries will be placed in the /usr/sbin/ path instead of the /usr/local/sbin/ path

1. Copy the appropriate binary to /usr/local/sbin/brick on the EZproxy server
2. Set permissions on the brick birnary
   • sudo chmod -v u=rwx,g=rx,o=rx /usr/local/sbin/brick

If for example you learn that EZproxy is running on a 32-bit Linux distribution, then you will want to deploy the brick-linux-386 binary to the EZproxy server as /usr/local/sbin/brick and set 0755 permissions on the file.

Configure brick

Start with the template configuration file

1. Copy the starter/template configuration file from contrib/brick/config.example.toml and modify accordingly using the configuration guide.
2. Configure one or more trusted IP Addresses
   • Per the default setting in the config file, only payload submissions from 127.0.0.1 will be accepted. You need to enter the IP Address of the Splunk system which is responsible for delivering JSON payloads to this application.
   • CAUTION: If you do not define a value for this setting, or comment it out, payload submissions from all sender IP Addresses will be accepted.
3. Decide whether you will enable automatic sessions termination or use fail2ban. See the fail2ban doc and the configuration guide for more information.
4. Set a Microsoft Teams webhook URL to enable Teams channel notifications.
   • Skip this step if you don't use Microsoft Teams.
5. Configure email notifications
   • Skip this step if you don't want email notifications.
   • NOTE: If your SMTP server applies Forward-confirmed reverse DNS (FCrDNS) verification the client_identity setting will need to reflect this.
6. Copy the starter/template "ignore" files and modify accordingly
   • /usr/local/etc/brick/ips.brick-ignored.txt
   • /usr/local/etc/brick/users.brick-ignored.txt

Firewall rules

You'll need to update the host firewall on the EZproxy server to permit connections from Splunk to the chosen IP Address and TCP port where brick will run. If possible, limit access to just the remote system submitting HTTP requests (as our example shows).

1. sudo ufw allow proto tcp from 192.168.2.2 to any tcp port 8000
   • skip this step if you plan to run this application on your system for local testing
     • e.g., localhost:8000

Results:

1. allow tcp protocol connections
2. from any source port on remote Splunk search head at 192.168.2.2
3. to any IP Address on EZproxy server
4. to tcp port 8000 where brick will listen for connections

Configure and deploy systemd unit

1. Copy the starter/template systemd unit file from contrib/systemd/brick.service and modify the ExecStart line to specify the path to a configuration file.
   • e.g., ExecStart=/usr/local/sbin/brick --config-file /usr/local/etc/brick/config.toml
   • NOTE: If you opt to deploy brick using the provided DEB or RPM packages then binaries will be placed in the /usr/sbin/ path instead of the /usr/local/sbin/ path
   • optionally, specify environment variables using a supported method to override default settings as needed
   • see the configuration guide for supported environment variables, command-line flags and configuration file settings
2. Copy to /etc/systemd/system/brick.service
3. Run sudo systemctl daemon-reload

Start brick now and enable it to start again at boot

1. sudo systemctl start brick
2. sudo systemctl enable brick