Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

4 Commits
README.md
README.md
 
 
defendcheck.py
defendcheck.py
 
 

Repository files navigation

Defend-Check

A Linux Defensive Audit & Baseline Monitoring Tool

DefendCheck is a lightweight, blue-team–focused security tool that performs a defensive audit of a Linux system. It gathers information about system configuration, privileges, network exposure, and authentication activity, then presents the results in a structured report.

The tool also supports baseline comparison, allowing defenders to detect security relevant changes over time.

DefendCheck is intended for:

  • Learning blue-team / SOC fundamentals
  • Endpoint triage and system hardening
  • Monitoring configuration drift
  • Portfolio demonstration of defensive security skills

System Requirements

Linux system (tested on Ubuntu/Debian-based distributions)

Python 3.8 or newer

Standard Linux utilities:

  • ss (for network inspection)
  • ufw or firewalld (for firewall checks)

Some checks require elevated privileges. The script runs without sudo, but results are more complete when run as root.

Setup

1) Clone or download the project

git clone https://github.com/YOUR_USERNAME/defendcheck.git

Or donload manually from the repository and place them into a directory.

2) Verify Python is installed

python3 --version

You shold see something like

Python 3.10.x

If not, install Python 3.

Running DefendCheck

Basic run (no special permissions)

python3 defendcheck.py

What this does

  • Runs all checks with whatever access your user has
  • Prints a readable summary to the terminal
  • Some checks may be skipped if permission is not granted

Use this when

  • You are testing the tool
  • You do not want to modify system permissions
  • You want a quick overview

Summary + JSON report (recommended)

python3 defendcheck.py --summary --json report.json

What this does

  • Prints a human-readable summary
  • Saves a full structured report to report.json

Why JSON matters

  • Easy to save, compare, and automate.
  • Can be converted to HTML, dashboards, or other formats later.

Baseline Mode (Change Detection)

Baseline mode allows the DefendCheck code to detect what has changed since you made your baseline use, this baseline use should be when your system is in a known-good state.

Create a baseline (known-good snapshot)

sudo python3 defendcheck.py --summary --save-baseline baseline.json

What this does

  • Saves the current system state as baseline.json.
  • This file should represent a "healthy" reference point.

IMPORTANT

  • If you run the code with sudo, the file will be owned by root.
  • In order to view you may want to change ownership.
  • When you run replace your username with where it says USER:USER.
    • Example: USER:USER --> robbi:robbi
sudo chown USER:USER baseline.json

Compare current state to baseline

sudo python3 defendcheck.py --summary --baseline baseline.json --json report.json

What this does

  • Runs a fresh scan
  • Compares results against the baseline
  • Highlights changes such as:
    • Firewall enabled/disabled
    • New privileged users
    • New listening ports
    • Auth log activity changes
    • Risk score changes

This mirrors how real secuirty tools detect configuration drift and persistence.

Viewing Reports in a Browser (Optional)

DefendChecks outputs JSON by design. JSON can be viewed directly or converted into HTML.

View JSON directly

xdg-open report.json

Convert JSON to HTML (no code changes)

  • Make sure you run this in the same directory that report.json is in
jq -r '
 "<html><body><h1>DefendCheck Report</h1><pre>" +
 (tojson | .) +
 "</pre></body></html>"
' report.json > report.html

xdg-open report.html

This approach reflects real world security workflows where tools will output JSON and then the reporting is handled separatley.

File Overview

File Purpose
defendcheck.py Main secrity audit script
report.json Output from a single run
baseline.json Known-good snapshot for comparison
report.html Optional HTML view (generated externally)

Typical Workflow Example

  1. Deploy or configure system
  2. Run DefendCheck and save a baseline
  3. Periodically rerun DefendCheck
  4. Compare against baseline
  5. Investigate unexpected changes

Understanding the Output (In Depth)

Here I will give an explanation of what each feature checks, why it matters, and how it can be used.

1) system_info

What it checks

  • Operating system and version
  • Kernal version
  • System uptime
  • Hostname and basic environment info

Why it matters: Security decisions depend heavily on context. The same alert can mean very different things on a brand-new VM versus a long-running production system.

  • Asset identification: This means clearly identifying which system you are looking at. In environments with many machines, confusing systems can lead to incorrect conclusions or wasted investigation time.

  • Vulnerability and patch context: Certain vulnerabilities only affect specific OS or kernel versions. Knowing this helps you reason about what kinds of attacks are even possible.

  • Timeline awareness: Uptime shows when the system last rebooted. Reboots can be normal (updates) or suspicious (attempts to clear evidence or restart compromised services).

If you see X, do Y

  • Very recent uptime: Ask why the system rebooted (updates vs unexpected restart).
  • Outdated OS/kernel: Check patch status and known vulnerabilities.

2) Firewall

What it checks

  • Whether a host-based firewall is installed and active (ufw or firewalld)

  • Fallback detection of iptables/nftables rules

Why it matters: A firewall is one of the most basic defensive controls. If it’s disabled, any listening service becomes directly reachable from the network.

  • Hardening validation: “Hardening” means configuring a system to be less exposed and harder to misuse. A firewall being enabled is one of the first hardening checks.

  • Exposure reduction: “Exposure” refers to how accessible a system is from the network. Firewalls reduce exposure by blocking traffic that shouldn’t reach the system.

  • Defense-in-depth: This means using multiple layers of protection. Even if a service is misconfigured, the firewall can still prevent access.

If you see X, do Y

  • Firewall inactive: Enable it and restrict inbound traffic to only what’s required.

  • Firewall unknown / unmanaged: Verify which tool is responsible for filtering traffic and ensure rules are intentional.

3) users_privileges

What it checks

  • UID 0 (root-equivalent) users

  • Members of sudo / wheel

  • Accounts with empty passwords (when run with sudo)

Why it matters: Privileges determine how much damage an account can do. Attackers often aim to gain or create privileged accounts to maintain long-term control.

  • Privilege audit: This is the process of reviewing who has elevated access and whether they actually need it. The goal is least privilege.

  • Persistence detection: “Persistence” means methods used to keep access over time. Creating new admin users is a common persistence technique.

  • Account hygiene: This refers to basic account safety checks, such as ensuring no accounts have empty passwords or unnecessary admin rights.

If you see X, do Y

  • More than one UID 0 user: Investigate immediately — this is rarely legitimate.

  • Unexpected sudo members: Review why they were added and remove if unnecessary.

  • Empty password account: Lock or secure the account immediately.

4) listening_ports

What it checks

  • Network ports currently listening for connections
  • Binding addresses (localhost vs all interfaces)
  • Owning processes (best with sudo)

Why it Matters: Every listening port is part of the system’s attack surface. If a service is listening, it can potentially be attacked.

  • Attack surface mapping: This means identifying all the “doors” into a system. Fewer doors generally means lower risk.

  • Exposure analysis: Determines whether services are reachable only locally or from the network. Services bound to 0.0.0.0 or : : may be externally reachable.

  • Service verification: Confirms that every running service is expected and intentional.

If you see X,do Y

  • New listening port since baseline: Identify the service and determine why it started.

  • Service bound to all interfaces: Restrict it to localhost or control access with firewall rules.

  • Unknown service: Investigate immediately.

5) auth_log_triage

What it checks

  • Failed login attempts
  • SSH failures and invalid users
  • Sudo ussage
  • User creation indicators

Why it matters: Logs show behavior, not just configuration. They help answer what is actually happening on the system.

  • Incident triage: Triage means quickly deciding whether something is normal or needs deeper investigation. Log patterns help prioritize attention.

  • Credential abuse detection: This means identifying attempts to misuse passwords or accounts (brute force attempts, invalid users).

  • Privillege abuse signals: Looks for unusual admin behavior, such as unexpected sudo usage or new user creation.

If you see X, do Y

  • High failed login volume: Investigate possible brute force attempts and consider blocking source IPs.

  • Unexpected user creation: Verify whether the account was expected or investigate for persistence.

  • Sudden sudo spikes: Review commands and timing for suspicious behavior.

6) Baseline Comparison

What it does

  • Saves a “known-good” snapshot of system state

  • Compares future runs against that snapshot

  • Highlights meaningful changes

Why it matters: Many security issues are discovered by noticing what changed, not by spotting something obviously malicious.

  • Change detection: Identifies differences over time, such as new users, new services, or firewall changes.

  • Configuration drift tracking: “Drift” means the system slowly becomes less secure due to updates, installs, or manual changes.

  • Faster investigations: Instead of asking “Is this bad?”, defenders ask “Why did this change?”

If you see X, do Y

  • New privileged user since baseline: Treat as high priority and investigate.

  • New listening service: Confirm whether it was intentionally added.

  • Firewall state changed: Determine who changed it and why.

7) Risk Score

What it does

  • Assigns a simple numeric and categorical risk level

  • Aggregates findings across all checks

Why it matters: Security teams must prioritize. Not everything can be fixed at once.

  • Prioritization: Helps decide which systems or findings need attention first.

  • Trend monitoring: Watching the score over time shows whether security posture is improving or degrading.

  • Communication: Makes it easier to explain system risk to non-technical stakeholders.

If you see X, do Y

  • Rising risk score: Investigate what changed and address the highest-impact findings first.

  • Sudden jump to HIGH/CRITICAL: Treat as a potential incident until proven otherwise.

Glossary and Security Philosophy

  • Hardening: tightening configuration to reduce easy weaknesses.

  • Exposure: how reachable your system/services are from the network.

  • Attack surface: all reachable services/doors into a system.

  • Triage: quick first-pass investigation to decide urgency/next steps.

  • Least privilege: users only get the access they need.

  • Persistence: ways an attacker keeps access long-term.

  • Drift: system gradually changes away from a known-good state.

DefendCheck is built around the idea that visibility comes before detection. Rather than attempting to exploit systems or identify malware directly, the tool focuses on understanding configuration, privileges, exposure, and change over time — the same signals human defenders rely on during investigations.

License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages