Project 4: System Inventory & Audit Tool

Build a filesystem audit tool that reports ownership, permissions, and anomalies.

Quick Reference

Attribute Value
Difficulty Advanced
Time Estimate 2-3 weeks
Language Shell + find/awk
Prerequisites find, permissions basics
Key Topics metadata queries, auditing, reporting

1. Learning Objectives

By completing this project, you will:

  1. Query file metadata using find predicates.
  2. Detect risky permissions and ownership anomalies.
  3. Generate inventory reports in text and CSV.
  4. Build repeatable audits for compliance.
  5. Handle large directory trees efficiently.

2. Theoretical Foundation

2.1 Core Concepts

  • File Metadata: inodes store size, owner, permissions, timestamps.
  • Permissions: rwx bits define access; misconfigurations are security risks.
  • Audit Rules: Define what counts as risky (world-writable, SUID).
  • Reporting: Summaries are more valuable than raw file lists.

2.2 Why This Matters

Auditing permissions and ownership is critical for security and compliance. This project teaches how to detect risky files quickly using standard tools.

2.3 Historical Context / Background

System admins have long used find for compliance checks. Modern security tools build on the same metadata queries, but with dashboards and automation.

2.4 Common Misconceptions

  • “Permissions are static”: They drift over time.
  • “find is slow”: It is efficient if you limit scope and avoid expensive actions.

3. Project Specification

3.1 What You Will Build

A CLI named audit-fs.sh that:

  • Scans directories for risky permissions
  • Reports ownership mismatches
  • Outputs summary counts and CSV exports

3.2 Functional Requirements

  1. Inventory: List files with owner, group, permissions, size.
  2. Rules: Detect world-writable, SUID/SGID, executable in temp.
  3. Reports: Summary counts + CSV export.
  4. Scopes: Include/exclude directories with flags.

3.3 Non-Functional Requirements

  • Safety: Read-only; no modifications.
  • Performance: Avoid costly file content reads.
  • Usability: Clear summary output.

3.4 Example Usage / Output

$ ./audit-fs.sh /var
World-writable files: 12
SUID binaries: 4
Unowned files: 2
Report saved to audit.csv

3.5 Real World Outcome

You run the tool on a server and receive:

  • A summary of risky permissions
  • A CSV report of all flagged files
  • A list of unowned files for cleanup

This output can be handed to security or compliance teams.

4. Solution Architecture

4.1 High-Level Design

+---------+    +---------+    +---------+
| Finder  | -> | Rule    | -> | Report  |
+---------+    +---------+    +---------+

4.2 Key Components

Component Responsibility Key Decisions
Finder Build file list prune dirs
Rule Engine Apply permission checks predicate order
Reporter Output summary CSV format

4.3 Data Structures

# counters for each rule
count_world_writable++
count_suid++

4.4 Algorithm Overview

Key Algorithm: Metadata audit

  1. Find files with predicates.
  2. For each file, check rule conditions.
  3. Log flagged files and increment counts.
  4. Output summary and CSV.

Complexity Analysis:

  • Time: O(F) for F files
  • Space: O(R) for report entries

5. Implementation Guide

5.1 Development Environment Setup

chmod +x audit-fs.sh

5.2 Project Structure

audit-fs/
├── audit-fs.sh
└── README.md

5.3 The Core Question You Are Answering

“How do I audit filesystem permissions and ownership quickly and safely?”

5.4 Concepts You Must Understand First

  1. Permission bits and modes
  2. SUID/SGID semantics
  3. find predicates and pruning

5.5 Questions to Guide Your Design

  1. Which directories should always be excluded?
  2. What permission patterns count as risky?
  3. How should CSV output be structured?

5.6 Thinking Exercise

List three permission patterns that should trigger alerts, and explain why.

5.7 The Interview Questions They Will Ask

  1. What is SUID and why is it risky?
  2. Why does find not need to read file contents?
  3. How do you avoid scanning system mounts?

5.8 Hints in Layers

Hint 1: Start with world-writable detection using -perm -0002.

Hint 2: Add SUID and SGID checks with -perm -4000 and -perm -2000.

Hint 3: Add CSV output with awk formatting.

5.9 Books That Will Help

Topic Book Chapter
File permissions “The Linux Command Line” Ch. 9
find usage “The Linux Command Line” Ch. 17

5.10 Implementation Phases

Phase 1: Inventory

  • Build file list

Phase 2: Rules

  • Apply permission filters

Phase 3: Reporting

  • Summaries and CSV output

6. Testing Strategy

6.1 Test Categories

Category Purpose Examples
Unit Tests Rule checks simulate permissions
Integration Tests Real dirs /tmp scan
Edge Cases Unreadable dirs error handling

6.2 Critical Test Cases

  1. World-writable file is detected.
  2. SUID binary is detected.
  3. Excluded directories are skipped.

7. Common Pitfalls and Debugging

Pitfall Symptom Solution
Scanning /proc slow or errors prune system dirs
Overbroad rules too many alerts tighten predicates
No CSV escaping broken output quote fields

8. Extensions and Challenges

8.1 Beginner Extensions

  • Add --json output

8.2 Intermediate Extensions

  • Add age-based filters

8.3 Advanced Extensions

  • Integrate with CIS benchmarks

9. Real-World Connections

  • Compliance audits
  • Security incident response

10. Resources

  • find manual
  • CIS benchmarks

11. Self-Assessment Checklist

  • I can explain permission bits
  • I can build find predicates safely

12. Submission / Completion Criteria

Minimum Viable Completion:

  • Report world-writable files

Full Completion:

  • Full audit summary + CSV

Excellence (Going Above and Beyond):

  • JSON output and compliance mappings