Imagine you run a website that stores files for thousands of users. Everything is running smoothly until one day, your server slows to a crawl and legitimate users can't get in. You check the logs and see one IP address sent 10,000 requests in the last minute. You've just been hit by a DDoS attack.

A DDoS (Distributed Denial of Service) attack is when someone floods your server with so many fake requests that it has no resources left to serve real users. It's like someone sending thousands of people to crowd a small shop so actual customers can't get in.

In this post I'll walk you through how I built an automated system that watches all incoming traffic, learns what normal looks like, and blocks attackers automatically — all without a human having to watch a screen.

What the Project Does

The system sits alongside a Nextcloud server (a self-hosted file storage app, like Google Drive) and does five things continuously:

1. Reads every HTTP request as it arrives

2. Counts requests per IP and globally

3. Learns what normal traffic looks like

4. Flags anything that deviates from normal

5. Blocks attackers at the firewall level and alerts the team on Slack

The entire thing runs as a background daemon — a program that never stops — and makes decisions in real time without any human involvement.

The Architecture

Before diving into the individual pieces, here is how everything connects:

Internet Traffic
      ↓
   Nginx (front door — logs every request as JSON)
      ↓
   Nextcloud (the actual app users interact with)
      ↓
   Your Detector (reads logs, runs math, blocks bad guys)
      ↓
   Dashboard + Slack Alerts + iptables blocks

Nginx sits in front of Nextcloud as a reverse proxy. Think of it like a receptionist — every visitor goes through it first. It writes down every visitor in a log file. Your detector reads that log file in real time.

Piece 1 — Reading the Logs

Nginx is configured to write logs in JSON format. Every single HTTP request produces one line like this:

{
  "source_ip": "41.58.2.1",
  "timestamp": "2024-11-14T15:04:05Z",
  "method": "GET",
  "path": "/login",
  "status": 200,
  "response_size": 4321
}

JSON is used instead of the default Nginx format because it is easy for Python to read. Instead of splitting strings, you just ask for a field by name:

data = json.loads(log_line)
ip = data["source_ip"]
status = data["status"]

The detector opens this file and reads it line by line forever. When there is no new line yet, it waits 50 milliseconds and tries again. This is called tailing a file — the same thing the tail -f command does in Linux.

Piece 2 — The Sliding Window

Once you have a log line, you need to answer one question: how many requests has this IP sent recently?

"Recently" is defined as the last 60 seconds. The naive approach would be counting requests per minute — but that has a problem. If an attacker sends 1000 requests in the last 5 seconds of one minute and the first 5 seconds of the next, each minute only shows 500. The per-minute counter misses the attack completely.

A sliding window fixes this. It always looks at the last 60 seconds from right now, regardless of where the clock minute boundary falls.

The data structure used is a deque (double-ended queue). Think of it as a list where you can efficiently add to one end and remove from the other.

Here is how it works:

from collections import deque
import time

window = deque()

# When a new request arrives, add it to the right
window.append((time.time(), is_error))

# Remove entries older than 60 seconds from the left
# Entries are in time order so oldest is always on the left
now = time.time()
while window and now - window[0][0] > 60:
    window.popleft()

# Current request rate = how many entries remain
rate = len(window)

As time moves forward, old entries fall off the left automatically. The window slides with time. At any moment, len(window) gives you the exact request count for the last 60 seconds.

Two windows are maintained simultaneously:

• Per-IP window — one deque per IP address

• Global window — one deque for all traffic combined

Piece 3 — The Baseline

Knowing the current rate is not enough. You need context. Is 15 requests per second a lot? It depends entirely on what normal looks like for your server.

At 3am, your server might normally get 2 requests per second. At noon it might get 30. A hardcoded threshold of "block anyone over 50 req/s" would miss the 3am attack and block legitimate noon traffic.

The solution is a rolling baseline — the system watches your actual traffic and learns what normal looks like.

Every second, the detector records how many requests arrived that second. It keeps a rolling 30-minute window of these per-second counts. Every 60 seconds it calculates two numbers from that data:

Mean — the average requests per second:

mean = sum(data) / len(data)

Standard deviation — how much the numbers normally vary from the mean:

variance = sum((x - mean) ** 2 for x in data) / len(data)
stddev = math.sqrt(variance)

These two numbers are your baseline. They update every 60 seconds so they always reflect recent reality. If your site gets a surge of legitimate traffic at noon, the baseline adjusts within a minute and stops treating that traffic as suspicious.

The system also keeps per-hour slots. Traffic at 9am tends to look different from traffic at 3am. When there is enough data for the current hour, it prefers that over the full 30-minute average — because the current hour is the most relevant comparison.

Floor values are applied to prevent extreme sensitivity during quiet periods:

effective_mean = max(mean, 1.0)    # never below 1 req/s
effective_stddev = max(stddev, 0.5) # never below 0.5

Without floors, a server with almost zero traffic at 3am would have a mean of 0.1 and a stddev of 0.05 — meaning the first legitimate morning user could trigger a ban.

Piece 4 — The Detection Logic

Now you have two things: the current rate for an IP, and the baseline for what normal looks like. The detection logic compares them using a Z-score.

A Z-score answers one question: how many standard deviations away from normal is this number?

zscore = (current_rate - mean) / stddev

If normal is 12 req/s and stddev is 2:

• 14 req/s → Z-score of 1.0 → within normal range

• 18 req/s → Z-score of 3.0 → suspicious

• 50 req/s → Z-score of 19.0 → definitely an attack

The system fires an alert when either of two conditions is true — whichever happens first:

# Condition 1 — statistically anomalous
if zscore > 3.0:
    flag_as_anomaly()

# Condition 2 — raw rate too high relative to baseline
elif current_rate > 5 * mean:
    flag_as_anomaly()

The second condition catches edge cases where the standard deviation is large (traffic varies a lot normally) and the Z-score alone might be too lenient.

There is also an error surge check. If an IP is getting a lot of 4xx or 5xx responses — errors — that suggests probing behavior. Someone trying every door hoping one is unlocked. When an IP's error rate exceeds 3x the baseline error rate, the detection thresholds for that IP are tightened automatically.

Global traffic is checked every 5 seconds using the same logic. A global spike means many IPs are attacking simultaneously — you cannot block all of them, so the system sends a Slack alert for the team to respond manually.

Piece 5 — Blocking with iptables

When an IP is flagged, it needs to be stopped immediately. Sending a message back saying "you're blocked" wastes server resources. The attack traffic needs to disappear before it even reaches Nginx.

iptables is the Linux kernel's built-in firewall. It sits at the very bottom of the network stack — below Docker, below Nginx, below everything. When you add a DROP rule for an IP, that IP's packets are thrown away at the kernel level. The attacker doesn't get an error message. Their connection simply never happens.

import subprocess

def ban(ip):
    subprocess.run([
        "iptables", "-I", "INPUT",
        "-s", ip,
        "-j", "DROP"
    ])

Breaking that command down:

• iptables — the firewall tool

• -I INPUT — insert at the TOP of the incoming traffic chain

• -s 41.58.2.1 — match traffic from this source IP

• -j DROP — silently discard the packet

The -I flag inserts at the top rather than appending to the bottom. This matters because iptables checks rules in order — if your DROP rule is at the bottom and there is an ACCEPT rule above it, traffic gets accepted before reaching your block.

The ban happens within 10 seconds of detection. A Slack message is sent simultaneously telling the team who was blocked, why, and how long the ban lasts.

The Unban Schedule

Not every block needs to be permanent. The system uses a backoff schedule:

A background thread checks every 10 seconds whether any ban has expired. When one has, it removes the iptables rule, updates the system state, and sends a Slack notification. If the same IP gets caught again, the next ban is longer.

To remove a ban:

subprocess.run([
    "iptables", "-D", "INPUT",
    "-s", ip,
    "-j", "DROP"
])

The Live Dashboard

A Flask web server runs on port 8080 and serves a page that refreshes every 3 seconds automatically using a simple HTML meta tag:

<meta http-equiv="refresh" content="3">

The dashboard shows:

• Currently banned IPs with countdown timers

• Global requests per second

• Top 10 source IPs

• CPU and memory usage

• Current baseline mean and stddev

• System uptime

Every page load collects fresh data from all components and rebuilds the HTML. Simple and reliable.

What I Learned

The most important insight from this project is that detection only works when it is relative. A hardcoded threshold is always wrong for someone. Traffic patterns are unique to every server, every time of day, every day of the week. The baseline approach means the system adapts automatically — it gets smarter the longer it runs.

The second insight is that separation of concerns makes complex systems manageable. Each file has exactly one job. The sliding window does not know about Slack. The notifier does not know about iptables. When something breaks, you know exactly which file to look at.

Source Code

The full source code is available at: https://github.com/RichardBenjamin/hng14-Stage3

The live metrics dashboard is available at: http://hngstagekene3.duckdns.org:8080

Built as part of the HNG DevSecOps track — Stage 3.

Introduction

Imagine pushing a Terraform file with a wildcard IAM role to production without realizing it. Oops. Now imagine getting a Slack notification seconds after the CI pipeline spots that misconfiguration. Much better, right?

This project will walk through the building and deployment of a lightweight Infrastructure-as-Code (IaC) misconfiguration scanner built in Go. This scanner integrates seamlessly into GitHub Actions and sends scan reports both as GitHub artifacts and to AWS S3—with Slack notifications to keep the team alert. The project guide is divided into four sections:

• Scanner Architecture and Logic

• GitHub Actions Pipeline Breakdown

• Creating AWS IAM User and S3 Bucket for CI Pipeline

• Slack Integration Setup

And the end of this guide, you'll have:

• A working IaC security scanner

• CI/CD automation with GitHub Actions

• Cloud storage of scan results in S3

• Real-time Slack alerts with links to the scan logs

Link to the project: https://github.com/RichardBenjamin/IAC-Scanner

Project Overview and Scanner Architecture

Project Structure

IAC-Scanner/
├── main.go                  # Entry point
├── scanner/
│   ├── scanner.go          # Main scanning logic
│   ├── docker.go           # Handles Dockerfile scans
│   ├── k8s.go              # Handles Kubernetes YAML scans
│   └── terraform.go        # Handles Terraform file scans
├── rules/
│   ├── rule.go             # Common rule structure
│   ├── docker_rules.go     # Rule definitions for Docker
│   ├── k8s_rules.go        # Rule definitions for Kubernetes
│   └── tf_rules.go         # Rule definitions for Terraform
├── test-files/             # Sample misconfigured files for testing

Scanner Architecture and Logic

The scanner project is written in Go and is structured in a modular way for clarity and ease of maintenance. It begins execution from the main.go file, which is the starting point of the program. This file accepts a command-line argument that specifies the folder or file path to scan. It then passes this path to the RunScanner function in scanner.go.

main.go

func main() {
    if len(os.Args) < 2 {
        fmt.Println("Usage: iac-scan <path-to-scan>")
        os.Exit(1)
    }
    path := os.Args[1]
    scanner.RunScanner(path)
}

Inside scanner.go, the RunScanner function creates a file named scan-results.log. This file will be used to store all scan results. The defer file.Close() line ensures that once scanning is done, the file is properly closed—even if an error occurs later. This setup provides a clean way to collect and save output from the scanner

As it encounters each file, it checks the file name and extension to determine its type. For example:

• Files ending in .tf are identified as Terraform files

• Files ending in .yaml or .yml are assumed to be Kubernetes YAML files

• Any file named Dockerfile or starting with "docker" is treated as a Dockerfile

Once the type is known, the corresponding handler function is called — CheckTerraform, CheckKubernetesYAML, or CheckDockerfile. These functions are defined in their respective files: terraform.go, k8s.go, and docker.go.

Each handler reads the content of the file and compares it with a list of predefined rules. These rules are written using regular expressions (regex), which are patterns used to search text. The rules are defined in separate files under the /rules/ folder. Each rule includes:

• A Name to identify it

• A Category to group it (like permissions, secrets, etc.)

• A Severity level (LOW, MEDIUM, or HIGH)

• A Pattern which is a regex used to match against the file's contents

• A Message to explain what was found

• An Enabled flag to turn the rule on or off

Rule Struct (in rule.go)

type Rule struct {
    Name     string
    Category string
    Severity string
    Pattern  string
    Message  string
    Enabled  bool
}

Rules are defined as structs and stored in slices, categorized by file type. A struct (short for structure) is a composite data type that groups together zero or more fields (variables) under a single name.

Sample of rules set in Kubernetes_rules.go

If a match is found between the rule and the file content, a function called ReportIssue is triggered. This function prints the issue to the terminal and also writes it into a file named scan-results.log. This makes it easy to view the output later or use it in CI/CD pipelines.

This approach makes the scanner easy to extend and organize allowing it to work well with automation tools like GitHub Actions. It also makes it fast and independent on external tools.

GitHub Actions Pipeline Breakdown

The GitHub Actions pipeline automates the entire scanning process every time someone pushes code or opens a pull request to the main branch. The breakdown of the pipeline is below.

Checkout Code

- name: Checkout Code
  uses: actions/checkout@v3

This step tells GitHub Actions to "check out" the repository code, meaning it pulls (clones) the contents of the repo into the runner. The runner is a temporary virtual machine that runs the workflow. Without this step, the runner would be empty and wouldn't know anything about the code!

Set up Go

- name: Set up Go
  uses: actions/setup-go@v4
  with:
    go-version: 1.22

This step installs the Go programming language in the workflow runner. The scanner is written in Go, so the runner needs Go installed to compile it. The version is kept at 1.22 to make sure the behavior is consistent with what the scanner was built and tested with. That avoids weird bugs that can happen when using a different version.

Build Scanner

- name: Build Scanner
  run: go build -o iac-scan

This command uses go build to compile the source code in the repo and outputs an executable file named iac-scan. The -o flag stands for "output". It tells the go build command what to name the executable file. Without -o, Go would just name the file after the directory by default.

Run Scanner

- name: Run Scanner
  run: ./iac-scan ./test-files > scan-results.log

The command ./iac-scan runs the executable file named iac-scan, which was compiled in the previous step. It takes ./test-files as the input directory, instructing the scanner to analyze the files contained within it. The > scan-results.log part redirects the scanner's output (stdout) into a file named scan-results.log, effectively saving the scan results instead of displaying them in the console.

Upload Artifact

- name: Upload Artifact
  uses: actions/upload-artifact@v2
  with:
    name: iac-scan-report
    path: scan-results.log

This line itells GitHub Actions to use a prebuilt action called upload-artifact, which is maintained by the official actions team at GitHub. The @v2 part specifies that the code uses version 2 of that action. The actions/upload-artifact@v2 action saves the scan-results.log file as a downloadable artifact named iac-scan-report.

Artifacts are files that GitHub Actions workflow uploads and saves after the run is complete. After the workflow finishes, find and download this artifact by going to the Actions tab of the GitHub repository and selecting the relevant workflow run.

Fail if HIGH Severity Issues Are Found

- name: Fail if HIGH severity issues are found
  id: scan_check
  run: |
    if grep -q "\[HIGH\]" scan-results.log; then
      message="High severity issues detected in files!"
      echo "message=$message" >> $GITHUB_OUTPUT
      exit 1
    else
      message="No HIGH severity issues found."
      echo "$message"
      echo "message=$message" >> $GITHUB_OUTPUT
    fi

The "Fail if HIGH severity issues are found" step in a GitHub Actions workflow checks the scan-results.log file for any lines marked with [HIGH] to identify critical security issues. Using a grep command, it determines whether such issues exist and sets a corresponding message output. If high- severity issues are detected, it records a failure message and exits with code 1, intentionally failing the job to enforce security policies. If no such issues are found, it logs a success message and allows the workflow to continue.

Configure AWS Credentials

- name: Configure AWS credentials
  if: always()
  uses: aws-actions/configure-aws-credentials@v2
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws-region: ${{ secrets.AWS_REGION }}

This step sets up the GitHub Actions environment with the necessary AWS credentials to interact with AWS services like S3. The aws-actions/configure-aws-credentials action configures the AWS CLI with the secret keys stored in GitHub Secrets. The if: always() condition ensures this step runs regardless of whether earlier steps fail or succeed—making it useful when uploading logs.

The --acl public-read flag is included to make the uploaded file publicly accessible via a direct URL. This is useful for sharing the scan results externally without requiring authentication. The AWS credentials (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY) are securely stored as GitHub Secrets and inserted into the workflow environment, so sensitive information are never exposed in the code.

Set log filename

- name: Set log filename
  if: always()
  id: logfile
  run: echo "filename=logs/log-${{ github.run_id }}.txt" >> $GITHUB_OUTPUT

This step creates a dynamic filename for the scan log file to be stored in the S3 bucket. By assigning a unique name using the github.run_id, each workflow run generates a distinct log file. The value is saved to an output variable called filename, which can be referenced later using steps.logfile.outputs.filename.

Upload to S3

- name: Upload to S3
  run: aws s3 cp scan-results.log s3://$AWS_S3_BUCKET/scan-results.log --acl public-read

The Upload to S3 step uses the AWS CLI command aws s3 cp to copy the scan-results.log file into an S3 bucket. The destination is specified as s3://$AWS_S3_BUCKET/scan-results.log, where $AWS_S3_BUCKET is an environment variable pointing to the name of the S3 bucket.

Generate Pre-signed S3 URL

- name: Get S3 Pre-signed URL
  if: always()
  id: signed_url
  run: |
    url=$(aws s3 presign s3://my-ci-logs-bucket/${{ steps.logfile.outputs.filename }} --expires-in 3600)
    echo "url=$url" >> $GITHUB_OUTPUT

This step creates a temporary, pre-signed URL that can be shared with others to access the scan log file in S3 without requiring AWS credentials. The link is valid for one hour (3600 seconds). The generated URL is stored in the output variable url for use in Slack notifications or other steps.

Notify Slack

- name: Notify Slack
  run: |
      curl -X POST -H 'Content-type: application/json' \
          --data "{
             \"text\": \"*Scan Complete*\\n${{ steps.scan_check.outputs.message }}\\n
           *S3 Logs:* <${{ steps.signed_url.outputs.url }}>
          *GitHub Artifact:* <https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}>
              \"}" \
              ${{ secrets.SLACK_WEBHOOK_URL2}}

The Notify Slack step uses curl to send a POST request to a Slack Incoming Webhook URL, which is stored securely as a GitHub Secret (SLACK_WEBHOOK_URL). An Incoming Webhook URL is a special Slack-generated URL that allows external systems, like GitHub Actions, to send messages directly into a Slack channel.

The message sent is a simple JSON payload that posts a notification saying " Scan complete! S3 Logs: [link]" — with the link pointing to the publicly accessible scan report on S3 and adds a direct link to the GitHub Actions run that produced this scan. This allows the team to get immediate alerts in a Slack channel whenever a scan finishes, making it easy to respond quickly to issues without having to dig into logs manually.

By joining all these steps together, a pipeline that scans every commit or pull request for infrastructure misconfigurations and immediately alerts the team with a downloadable report.

Creating AWS IAM User and S3 Bucket for CI Pipeline

To connect GitHub Actions workflow to AWS, a AWS IAM user that has access to a specific S3 bucket where the scan reports will be stored is needed.

Step 1: Create IAM User for CI

Go to the AWS IAM Dashboard and click Users > Add user. Name the user something like github-ci-user. Under Access Type, check:

• Programmatic access (for access key and secret)

• AWS Management Console access to manually log in later

  

  Image showing the creation of IAM User

Step 2: Set User Permissions

On the next page, choose Attach policies directly and pick AmazonS3FullAccess. This grants full access to all Amazon S3 resources within an AWS account. When this policy is attached to an IAM user, group, or role, it allows that entity to perform any action (s3:*) on any bucket or object (*) in Amazon S3.

Image showing policy attached to user

Step 3: Generate Access Keys

After the user is created, go to Security credentials tab > Create access key. Choose "Application running outside AWS". This tells AWS that the access key is intended for use in an environment that is not within the AWS like Github Actions. Copy the Access Key ID and Secret Access Key and store them because the secrets won’t be able to be viewed again, and leaking it can allow full programmatic access to the AWS resources depending on the permissions tied to the user.

Image showing the generation of Access Keys

Step 4: Add Access to GitHub Secrets

Go to the GitHub repository > Settings > Secrets and variables > Actions. Add:

• AWS_ACCESS_KEY_ID

• AWS_SECRET_ACCESS_KEY

• AWS_S3_BUCKET

  

  Repository secrets in GitHub Actions workflow.

Step 5: Create S3 Bucket

Now go to the S3 service in AWS and click Create bucket. Enter a unique name (e.g., iac-ci-logs) and select a region. Leave other settings default and click Create.

Image showing the creation of S3 bucket

Step 6: Make Bucket Object Public

To directly the Slack notification to the report, allow public read access to the file. To do this add an ACL or edit the bucket policy.

Image showing the creation of S3 Bucket policy

Slack Integration Setup

To ensure that the team gets immediate feedback when IaC misconfigurations are found, slack is integrated into the CI process. This involves creating a Slack App that can send messages to the desired Slack channel using incoming webhooks and OAuth tokens.

Step 1: Create a Slack App

Go to Slack API and click Create New App. Choose From scratch. Then name the app (e.g., IAC-Scanner-Alert) and select the appropriate Slack workspace.

Image showing the creation of slack app

Image showing the selection of App name and workspace

Step 2: Add Scopes and Permissions

Inside the app settings, go to OAuth & Permissions. Under Bot Token Scopes, add the following:

• incoming-webhook – To allow posting to channels

• chat:write – To enable the app to send messages

  

Image showing OAuth Scopes section showing selected scopes

Step 3: Install App to Workspace

Scroll to the top and click Install App to Workspace. You'll be redirected to grant permissions. Choose the channel the app can post to (e.g., #all-devsecops) and authorize.

Image showing permission request for a selected channel

Step 4: Copy Credentials

After installation, this will be provided:

• A Bot User OAuth Token (starts with xoxb-...)

• A Webhook URL for the selected channel

  

Image showing the Bot User OAuth Token to be copied

Copy these and add them to the GitHub repository’s secrets as:

• SLACK_WEBHOOK_URL

• SLACK_BOT_TOKEN

Step 5: Test the Application

After the Slack has been set up and the channel has invited the app. Test the scanner alert by running the scanner with the sample misconfigured IaC files in the testing folder. The following alert would look like this:

Image showing the links to the log send to the slack channel through the app.

Errors Encountered and How I Handled Them

Conclusion

This project builds a Go-based IaC scanner that detects misconfigurations in Terraform, Kubernetes, and Docker files using regex rules. It automates its execution in a GitHub Actions pipeline, where results are saved as artifacts, pushed to AWS S3, and shared via Slack alerts. It’s a lightweight, approach to add security to CI/CD workflows and helps the team catch issues early. If you enjoyed this, feel free to share, comment, and connect!

Security is an important part of system administration, and one of the most common attack vectors on a Linux system is unauthorized login attempts. These often come in the form of brute-force attacks on SSH or other authentication methods. In this article, I will walk you through how to create a Bash script that not only monitors login failures in real time but also captures the attackers's identity using a webcam and emails a detailed alert to the system owner.

Why Bash?

Bash (Bourne Again SHell) is a widely-used command-line interpreter that is standard in most Unix-like systems. It's powerful for automation tasks due to its:

• Ease of use: It has a simple syntax, readable logic.

• Universality: It is present on almost every Linux system.

• Efficiency: It is excellent for file monitoring, log analysis, process automation, etc.

• No need for external dependencies: It uses built-in tools like grep, tail, ping, etc.

When paired with other Unix utilities, Bash becomes a powerful tool for building lightweight security scripts.

What does the Script do?

The script achieves the following key functions:

1. Real time monitoring of login attempts from the device authentication log.

2. Captures Identity of user attempting login after three consecutive failed login attempts.

3. Stays active probing for internet connectivity to send an Email to the Owner in cases where the device is not connected to the internet when the attack happens.

4. Alerts the Owner’s Email Address the Time and captured Image of user currently attempting login.

5. Schedules the script to run automatically when the user initiates a login, using a cron job.

Access the script via: https://github.com/RichardBenjamin/login-monitor-alert/

Linux Utilities Used

A brief description of the key tools and commands used in the script are outlined below:

• tail -F: To follow and monitor the Authentication log file; /var/log/auth.log in real time.

• tee: To write log lines to another file for analysis and auditing.

• grep: To search for specific keywords like “authentication failure".

• fswebcam: Lightweight command-line tool to capture webcam images.

• ping: Used to check if internet connectivity is available.

• msmtp: A simple SMTP client to send emails through external SMTP servers.

• uuencode: Encodes binary files (images) so they can be attached via email.

• truncate: Clears log file contents before use to avoid processing old data.

• cron: A time-based job scheduler used to automate the script execution.

• rsyslog: A high-performance logging service used in Linux systems to collect, process, and store log messages.

• TLS: is a cryptographic protocol designed to provide secure communication over a network, especially for web browsing, email, and other internet services.

Tools used in the script, I installed using the command below on my Linux Distro:

sudo apt update && sudo apt install fswebcam msmtp sharutils

Step-by-step process of script implementation and execution

Step 1: Create the Script File

touch login-monitor.sh
chmod +x login-monitor.sh

Create a .sh file with a name of your choosing. For my script, I used the touch command to create the file then named it login-monitor.sh. Make the file executable with the chmod +x command.The “chmod +x” command is a basic Unix permission command that makes files or binaries executable. So, if the file is not executable, the shell will not allow direct execution in a format like ./login-monitor.sh.

Step 2: Initialize and Prepare Log Paths

LOGFILE="/var/log/auth.log"
COPY_LOG="/home/kene/Documents/Project/Scripts/auth_copy.log"
THRESHOLD=3
FAIL_COUNT=0

truncate -s 0 "$COPY_LOG"

• Open the script with an editor (Vim, Nano, etc) of your choosing.

• Initialize and prepare log paths for the script.

• The auth_copy.log in the path assigned to the variable COPY_LOG stores copied logs for the current session in real time from /var/log/auth.log .

• To prevent disrupting auditing processes, the auth_copy.log file is used for auditing and analysis instead of the /var/log/auth.log .

• The /var/log/auth.log is managed by rsyslog thus tampering it may cause logging issues and violate compliance standards. Using the auth_copy.log file completely removes sudo permission-request errors.

• truncate -s 0 clears any previous logs in the auth_copy.log file. This allows new logs for a fresh session be analysed without confusion.

Step 3: Monitor Logs in Real-Time and Mirror to Backup

tail -F "$LOGFILE" | tee -a "$COPY_LOG" | while read -r line; do

• • tail -F "$LOGFILE": This command continuously monitors /var/log/auth.log in real-time.

    • tee -a "$COPY_LOG": The tee command after reading each new line from the /var/log/auth.log appends a copy to auth_copy.log using the -a option. This means the command will add new logs to the auth_copy.log without modifying its existing contents.

    • while read -r line; do: This line applies this conditional logic on each log line appended by the tee command.

Step 4: Handle Successful Login Events

if echo "$line" | grep -q "session opened for user"; then
    echo "Successful login detected: $line"
    FAIL_COUNT=0
    handle_success
    exit 0  #  To ensure complete termination
fi

Breakdown of IF condition successful Login Attempts:

• grep -q "session opened for user": This filters lines from the log that indicate a successful user login. It basically searches for the phrase session opened for user inside the auth_copy.log file. The -q option which means quiet mode hides the detail of the grep -q "session opened for user" command from displaying on the terminal.

• echo "Successful login detected: $line": This receives input from grep -q "session opened for user" command, parses the input to the $line then indicates who successfully logged in and when via the terminal.

• FAIL_COUNT=0: This resets the failed login counter to avoid false positives. If the legitimate user logs in successfully, the alert logic is halted.

• handle_success: This function handles termination of the script. It exits the script and intercept signals if needed.

• exit 0: Ensures immediate exit from the script's current execution context after a valid login is confirmed. exit 0 alone doesn’t stop all background processes, it's added to complement the handle_success function in termination of the script. Get detailed explanation of the handle_success function here.

Step 5: The handle_success() Function

The helper function is defined to handle a clean script exit when a successful login is detected:

handle_success() {
    kill 0  # Terminates all processes in the current script group
    exit 0  # Ensures script stops immediately
}

In a normal Bash script, exit 0 is used to stop the script, but in this case, it's not enough. The reason is because this script relies on a pipeline that includes tail -F, tee, and while read, which creates a subshell.

Calling exit 0 within this loop only exits the subshell — it does not terminate the tail and tee processes that are still running. As a result, the script continues running in the background and does not stop after the login has been successful.

To solve this, use this command inside the script in form of a function:

handle_success() {
    kill 0  # Terminates all processes in the current script group
    exit 0  # Ensures script stops immediately
}

This sets up signal handling that allows the script to intercept termination signals and shut down all processes after the login has been successful.

Step 6: Detecting Failed Login Attempts

This section deals with the intrusion detection system (IDS). It looks for failed authentication entries in the log and tracks the number of consecutive failures:

if echo "$line" | grep -q "authentication failure"; then
    ((FAIL_COUNT++))
    if [ "$FAIL_COUNT" -ge "$THRESHOLD" ]; then
        echo "ALERT: $THRESHOLD consecutive login failures detected!"

Breakdown of IF condition failed Login Attempts:

• grep -q "authentication failure": This searches the log line for the keyword indicating a failed login attempt.

• ((FAIL_COUNT++)): This increments the failure counter using Bash’s arithmetic evaluation to keep track of how many consecutive failures have occurred.

• if [ "$FAIL_COUNT" -ge "$THRESHOLD" ]: Once the failure count reaches or exceeds the predefined 3 attempts in threshold, it triggers the next part of the script, which is an email alert.

• echo "ALERT:...": This provides visual feedback of output on the terminal.

Step 7: Capture Attacker’s Snapshot

After the script detects the defined number of failed login attempts, it moves to collect evidence — capturing an image of the person attempting unauthorized access and the time of the access:

cd /home/kene/Project/DevOps
fswebcam snapshot.jpg > fswebcam.log 2>&1
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')

Breakdown of the Snapshot process:

• cd /home/kene/Project/DevOps: Change directory to the folder snapshots are to be saved. This ensures that the snapshot and webcam logs are saved in a centralized location for easy access.

• fswebcam snapshot.jpg: This prompts the fswebcam utility to take a photo using the system’s default webcam. The Image is then saved with name as defined in the Script.

• > fswebcam.log 2>&1: This redirects both the Standard Output (stdout) and Standard Error (stderr) to fswebcam.log file.

• TIMESTAMP: This is used to get the exact date and time the snapshot was taken. It saves the initial time and date for when the Owner receives the email incase the internet is out at that time.

Step 8: Email the Alert with Attachment

Once the attacker’s image has been captured and saved, the next step is to notify the system owner via email. This is handled using the on_internet_connected function:

on_internet_connected() {
    (echo "Subject: URGENT SECURITY ALERT";
     echo "We have detected 3 consecutive login failures on your system, which indicates an unauthorized access attempt by this attacker. The attacker, whose identity has been attached to the mail, attempted to breach your system at"; 
     echo "$TIMESTAMP"
     uuencode /home/kene/Project/DevOps/snapshot.jpg snapshot.jpg) | msmtp okekerichard281@gmail.com
}

Breakdown of the Email Notification process:

• Email Subject and Body: Uses echo to craft the email's subject and body. It provides clear context that an intrusion attempt was detected and that visual evidence has been attached.

• $TIMESTAMP: Appends the exact date and time the alert was triggered. This makes the alert more traceable for the system owner.

• uuencode: Converts the image file into an email-friendly format so it can be attached as snapshot.jpg.

• msmtp: A lightweight SMTP client used to send the actual email. It forwards the entire message to the configured email address.

• 

Step 9: Configuring msmtp file

Properly configure the msmtp file so that the script can successfully send emails.

Note that msmtp reads settings from a config file, typically located at ~/.msmtprc.

Here’s a basic example configuration for Gmail:

# ~/.msmtprc
account        gmail
host           smtp.gmail.com
port           587
from           your-email@gmail.com
user           your-email@gmail.com
password       abcd efgh ijkl mnop  # Replace this with your App Password
auth           on
tls            on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
logfile        ~/.msmtp.log

Key Fields Explained:

• account: Defines the owner’s account to use when sending mail.

• host: The SMTP server of your mail provider.

• port: SMTP port (usually 587 for Transport Layer Security).

• user and from: Add sender email address.

• password: A 16-character password is used instead of the real password in the msmtprc file.

• tls and tls_trust_file: Ensures the email is securely transmitted.

To automate the Security alert Email process, configure msmtp to work with Gmail. However, due to Google's security restrictions, direct password authentication was not allowed. To work around this, generate an App Password, which would allow msmtp to send emails securely.

To generate an App Password;

• navigate to Google Account ==> Security

• Scroll down to "Signing in to Google"

• Ensure that 2-Step Verification is enabled. This is a requirement for successfully generating an App Password.

• If 2-Step Verification is successfully enabled, proceed to the Google App Passwords page.

• Click "Generate" to get a 16-character App Password in a format like abcd efgh ijkl mnop.

• Carefully copy this password and integrate it into the msmtprc configuration file. Now, the system can send emails securely without using the actual Gmail password.

Step 10: Waiting for Internet Before Sending Alert

To ensure that the email can be sent successfully, the script checks for internet connectivity before executing the on_internet_connected function:

check_internet() {
    ping -c 1 google.com &> /dev/null
}

while true; do
    if check_internet; then
        on_internet_connected
        break
    fi
    sleep 10
fi

Breakdown of the Connection process:

• check_internet(): This function attempts to ping Google once (-c 1). The &> /dev/null redirects both stdout and stderr to /dev/null, effectively silencing the command's output. If the ping is successful, the function returns 0, which Bash treats as true.

• while true; do ... done: This loop runs endlessly until check_internet returns true, i.e. an internet connection is detected.

• sleep 10 : This prevents the loop from overwhelming the system by adding a 10-second pause between each connectivity check.

• on_internet_connected: This is called once a connection is confirmed, this function handles sending the alert email with the snapshot.

Scheduling with Cron

Once the script is fully functional, the next step is to automate its execution. This ensures it starts running without requiring manual intervention — especially after reboot.

Configure cron for the root user

Because the script needs access to /var/log/auth.log (which requires root privileges), Edit the root user’s crontab:

sudo crontab -e

Add the path to run the script file at system startup

@reboot path-to-script-file
# Example @reboot /home/kene/Project/DevOps/Scripts/login-monitor.sh

Errors Encountered and how I Handled them

Conclusion

This project showcases how Bash scripting can be used to build a real-time security alert system. By monitoring system logs, tracking log-in behavior, taking snapshots with a webcam, and sending automated alerts, I gained practical experience in Bash scripting, Linux security, and automation.

If you found this guide helpful or want to make a contribution, feel free to reach out via:

1. View the GitHub Repository

2. Connect with me on LinkedIn

3. Connect with me on X