{"id":4666,"date":"2026-09-21T03:01:02","date_gmt":"2026-09-20T21:31:02","guid":{"rendered":"https:\/\/cpanelfree.com\/blog\/linux-auditd-framework-writing-custom-audit-rules-to-detect-unauthorized-file-access\/"},"modified":"2026-09-21T03:01:02","modified_gmt":"2026-09-20T21:31:02","slug":"linux-auditd-framework-writing-custom-audit-rules-to-detect-unauthorized-file-access","status":"publish","type":"post","link":"https:\/\/cpanelfree.com\/blog\/linux-auditd-framework-writing-custom-audit-rules-to-detect-unauthorized-file-access\/","title":{"rendered":"Linux Auditd Framework: Writing Custom Audit Rules to Detect Unauthorized File Access"},"content":{"rendered":"

Detecting stealthy tampering, unauthorized privilege escalations, and unauthenticated file access in enterprise Linux environments requires a deterministic kernel-level auditing mechanism rather than reactive userland log scrapers. When multi-tenant hosts or mission-critical servers handle sensitive data on platforms like CpanelFree<\/a>, administrators must isolate and trace every file system interaction down to the syscall invocation without degrading I\/O throughput. Deploying precision audit rules within the Linux Audit Daemon (auditd<\/code>) provides real-time visibility into unauthorized reads, writes, and inode modifications while maintaining sub-millisecond execution overhead.<\/p>\n

<\/p>\n

What is the Linux Auditd Framework and How Does It Detect File Access?<\/h2>\n
\n Direct Answer:<\/strong> The Linux Auditd framework intercepts kernel system calls (such as open<\/code>, openat<\/code>, truncate<\/code>, and unlink<\/code>) via the Linux kernel audit subsystem (kauditd<\/code>) before userland execution completes. By defining deterministic file-watch rules (-w<\/code>) or exit-code filtered syscall rules (-a always,exit -F arch=b64 -S ... -F exit=-EACCES<\/code>), auditd captures the actor UID, immutable login AUID, process PID, executable path, and file inode directly into \/var\/log\/audit\/audit.log<\/code> without application-level cooperation.\n<\/div>\n

The Architecture of the Linux Kernel Audit Subsystem<\/h3>\n

To write performant audit rules, systems architects must understand the path a file request traverses across the Linux kernel boundary. The audit architecture consists of three operational tiers:<\/p>\n

    \n
  • Kernel Audit Subsystem (kauditd<\/code>):<\/strong> Hooked directly into the system call dispatch table and the Virtual File System (VFS) layer. When an application invokes a syscall to access a file, kauditd<\/code> evaluates the request against active in-memory filter lists (task<\/code>, exit<\/code>, user<\/code>, and exclude<\/code>). If a rule matches, the kernel packages an audit event and places it onto a high-speed netlink socket ring buffer.<\/li>\n
  • Userland Daemon (auditd<\/code>):<\/strong> A dedicated background process that consumes raw netlink datagrams from the kernel buffer, applies formatting, writes chronologically to \/var\/log\/audit\/audit.log<\/code>, and rotates log files according to disk pressure policies.<\/li>\n
  • Audit Dispatcher & Plugins (audispd<\/code> \/ auditd-plugins<\/code>):<\/strong> A real-time multiplexer that forwards events to external consumers, such as centralized SIEM endpoints, Syslog daemons, or anomaly detection pipelines.<\/li>\n<\/ul>\n

    The primary advantage of this architecture over file integrity monitoring tools (such as AIDE or Tripwire) is temporal immediacy: while integrity checkers only detect changes after the fact via periodic cron hashes, auditd<\/code> captures both successful and denied<\/em> access attempts at the exact microsecond they occur.<\/p>\n

    Comparing Audit Methods: Naive File Watches vs. Precision Syscall Filters<\/h2>\n

    Many administrators configure basic file watches using the -w \/path\/to\/file -p rwa -k key<\/code> syntax. While straightforward, naive file watches generate immense log volume on busy servers because they trigger on every single access<\/em>, regardless of whether the operation was authorized or failed due to permission constraints. In high-density hosting or database environments, logging millions of routine reads exhausts I\/O buffers and creates severe performance bottlenecks.<\/p>\n

    By contrast, enterprise-grade audit configurations leverage exit-filtered system call rules<\/strong>. By instructing the kernel to log only when a system call terminates with -EACCES<\/code> (Permission Denied) or -EPERM<\/code> (Operation Not Permitted), administrators isolate genuine unauthorized access attempts while ignoring millions of legitimate operations.<\/p>\n\n\n\n\n\n\n\n\n\n
    Architectural Metric<\/th>\nStandard File Watch (-w<\/code>)<\/th>\nTuned Syscall Filter (-a always,exit<\/code>)<\/th>\n<\/tr>\n<\/thead>\n
    Target Scope<\/td>\nSpecific path or directory tree<\/td>\nVFS syscalls across selected files or globally<\/td>\n<\/tr>\n
    Event Filtering<\/td>\nTriggers on all matching permissions (r\/w\/x\/a)<\/td>\nFilters by exit code (e.g. exit=-EACCES<\/code>, exit=-EPERM<\/code>)<\/td>\n<\/tr>\n
    Log Volume & Noise<\/td>\nExtremely High (Gigabytes\/hr on active files)<\/td>\nMinimal (Zero noise during normal operations)<\/td>\n<\/tr>\n
    CPU & Storage Overhead<\/td>\nModerate to High under sustained I\/O<\/td>\nNegligible (< 1% CPU utilization on NVMe arrays)<\/td>\n<\/tr>\n
    Forensic Depth<\/td>\nPath, PID, UID, Comm<\/td>\nSyscall args, AUID, EUID, FSUID, Inode, Return Code<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    \n Architecture Note — The Critical Role of AUID:<\/strong> The Audit Login User ID (auid<\/code>) is recorded by the kernel when a user first authenticates via SSH, console, or display manager. Even if an attacker executes sudo su -<\/code> or uses a setuid binary to switch their effective UID to 0 (root), their auid<\/code> remains permanently tied to their original authentication identity. Never rely solely on uid<\/code> or euid<\/code> when analyzing security logs; auid<\/code> represents the immutable chain of custody.\n<\/div>\n

    Production Configuration: Daemon Optimization & Ruleset Deployment<\/h2>\n

    Deploying audit rules requires two complementary configuration files: the daemon performance profile (\/etc\/audit\/auditd.conf<\/code>) and the rule definition set (\/etc\/audit\/rules.d\/50-unauthorized-access.rules<\/code>). Modern Linux distributions utilizing auditd<\/code> 3.x+ compile individual rule files in \/etc\/audit\/rules.d\/<\/code> into a single contiguous ruleset loaded into the kernel using augenrules<\/code>.<\/p>\n

    1. Production Daemon Tuning (\/etc\/audit\/auditd.conf<\/code>)<\/h3>\n

    Before loading rules, optimize the userland daemon to prevent disk starvation and ensure high-throughput event processing during sustained traffic spikes:<\/p>\n

    # \/etc\/audit\/auditd.conf - Enterprise Production Profile\nlocal_events = yes\nwrite_logs = yes\nlog_file = \/var\/log\/audit\/audit.log\nlog_group = root\nlog_format = ENRICHED\nflush = INCREMENTAL_FLUSH\nfreq = 50\nmax_log_file = 200\nnum_logs = 10\npriority_boost = 4\nname_format = HOSTNAME\n\n## Space Management & Failure Resilience\nmax_log_file_action = ROTATE\nspace_left = 500\nspace_left_action = SYSLOG\nadmin_space_left = 100\nadmin_space_left_action = SUSPEND\ndisk_full_action = SUSPEND\ndisk_error_action = SUSPEND\nuse_libwrap = yes\nverify_email = yes\naction_mail_acct = root\n<\/code><\/pre>\n
    2. Custom Audit Ruleset (\/etc\/audit\/rules.d\/50-unauthorized-access.rules<\/code>)<\/h3>\n
    The following ruleset establishes a hardened security baseline. It monitors critical configuration repositories, sensitive authentication databases, and kernel-level file access syscalls, flagging every operation that fails with EACCES<\/code> or EPERM<\/code> across both 64-bit and 32-bit execution layers.<\/p>\n
    ## \/etc\/audit\/rules.d\/50-unauthorized-access.rules\n## Enterprise Unauthorized File Access & Integrity Detection Rules\n\n# 1. Reset existing rules and set buffer size\n-D\n-b 8192\n\n# 2. Failure mode: 1 = printk notice, 2 = kernel panic (for ultra-high-security)\n-f 1\n\n# 3. Rate limiting (0 = unconstrained)\n-r 0\n\n## ====================================================================\n## SECTION A: Precision Syscall Monitoring for Unauthorized Access\n## Logs ANY file open\/truncate\/delete that terminates in EACCES or EPERM\n## ====================================================================\n\n# 64-bit Architecture - File Access Denials\n-a always,exit -F arch=b64 -S open,openat,openat2,creat,truncate,ftruncate -F exit=-EACCES -k unauthorized_file_access\n-a always,exit -F arch=b64 -S open,openat,openat2,creat,truncate,ftruncate -F exit=-EPERM  -k unauthorized_file_access\n\n# 32-bit Compatibility Layer - File Access Denials\n-a always,exit -F arch=b32 -S open,openat,creat,truncate,ftruncate -F exit=-EACCES -k unauthorized_file_access\n-a always,exit -F arch=b32 -S open,openat,creat,truncate,ftruncate -F exit=-EPERM  -k unauthorized_file_access\n\n# 64-bit Architecture - Unauthorized File Deletion & Renaming Attempts\n-a always,exit -F arch=b64 -S unlink,unlinkat,rename,renameat,renameat2 -F exit=-EACCES -k unauthorized_file_deletion\n-a always,exit -F arch=b64 -S unlink,unlinkat,rename,renameat,renameat2 -F exit=-EPERM  -k unauthorized_file_deletion\n\n# 64-bit Architecture - Unauthorized Permission & Ownership Modification\n-a always,exit -F arch=b64 -S chmod,fchmod,fchmodat,chown,fchown,fchownat,lchown -F exit=-EACCES -k unauthorized_attr_change\n-a always,exit -F arch=b64 -S chmod,fchmod,fchmodat,chown,fchown,fchownat,lchown -F exit=-EPERM  -k unauthorized_attr_change\n\n## ====================================================================\n## SECTION B: Targeted Watches on High-Value System Assets\n## ====================================================================\n\n# Authentication & Identity Repositories\n-w \/etc\/passwd -p wa -k identity_tampering\n-w \/etc\/shadow -p rwa -k credentials_access\n-w \/etc\/gshadow -p rwa -k credentials_access\n-w \/etc\/security\/opasswd -p rwa -k credentials_access\n-w \/etc\/sudoers -p wa -k privilege_escalation\n-w \/etc\/sudoers.d\/ -p wa -k privilege_escalation\n\n# SSH Infrastructure\n-w \/etc\/ssh\/sshd_config -p wa -k sshd_config_modification\n-w \/etc\/ssh\/sshd_config.d\/ -p wa -k sshd_config_modification\n-w \/root\/.ssh\/ -p rwa -k root_ssh_keys\n\n# System Configuration & Service Control\n-w \/etc\/systemd\/ -p wa -k systemd_unit_modification\n-w \/etc\/ld.so.conf -p wa -k dynamic_linker_tampering\n-w \/etc\/ld.so.conf.d\/ -p wa -k dynamic_linker_tampering\n-w \/etc\/pam.d\/ -p wa -k pam_tampering\n\n# Storage & Mount Configurations\n-w \/etc\/fstab -p wa -k filesystem_mount_tampering\n\n## ====================================================================\n## SECTION C: Audit Configuration Immutability (Self-Defense)\n## ====================================================================\n-w \/etc\/audit\/ -p wa -k audit_config_tampering\n-w \/var\/log\/audit\/ -p wa -k audit_log_tampering\n\n# Make configuration immutable until system reboot (uncomment in production)\n# -e 2\n<\/code><\/pre>\n
    \n  Security Hardening Alert — The -e 2<\/code> Directive:<\/strong> Adding -e 2<\/code> as the final rule locks the audit configuration directly in the kernel. Once active, no process—not even root<\/code>—can add, delete, or modify audit rules, nor stop the audit daemon. Any attempt to modify rules requires a full system reboot. Always verify your rules thoroughly before enabling this flag in production.\n<\/div>\n
    Testing, Verification, and Forensic Log Analysis<\/h2>\n
    After creating the ruleset, load it into the active kernel and verify that the rules are operational without syntax errors:<\/p>\n
    # Compile rules from \/etc\/audit\/rules.d\/ into \/etc\/audit\/audit.rules and load\naugencules --load\n\n# Verify active rules in the running kernel\nauditctl -l\n<\/code><\/pre>\n
    Simulating an Unauthorized Access Attempt<\/h3>\n
    To confirm that our syscall rules trigger accurately on permission denial, create a test file restricted to root permissions, switch to an unprivileged account, and attempt to read it:<\/p>\n
    # Create restricted test file\ntouch \/opt\/restricted_payroll_data.db\nchmod 600 \/opt\/restricted_payroll_data.db\n\n# Attempt unauthorized access as an unprivileged user\nsu - testuser -c \"cat \/opt\/restricted_payroll_data.db\"\n# Expected output: cat: \/opt\/restricted_payroll_data.db: Permission denied\n<\/code><\/pre>\n
    Parsing the Generated Audit Log with ausearch<\/code> and aureport<\/code><\/h3>\n
    Query the audit log specifically for events tagged with our custom key unauthorized_file_access<\/code>:<\/p>\n
    # Query events with enriched, human-readable translation (-i)\nausearch -k unauthorized_file_access -ts recent -i\n<\/code><\/pre>\n
    The resulting log output reveals the full anatomical context of the intercepted system call:<\/p>\n
    type=PROCTITLE msg=audit(09\/21\/2026 02:45:12.894:1042) : proctitle=cat \/opt\/restricted_payroll_data.db\ntype=PATH msg=audit(09\/21\/2026 02:45:12.894:1042) : item=0 name=\/opt\/restricted_payroll_data.db inode=524312 dev=fd:00 mode=file,600 ouid=root ogid=root rdev=00:00 nametype=NORMAL cap_fp=none cap_fi=none cap_fe=0 cap_fver=0\ntype=CWD msg=audit(09\/21\/2026 02:45:12.894:1042) : cwd=\/home\/testuser\ntype=SYSCALL msg=audit(09\/21\/2026 02:45:12.894:1042) : arch=x86_64 syscall=openat success=no exit=EACCES(Permission denied) a0=0xffffff9c a1=0x7ffe42b91870 a2=O_RDONLY a3=0x0 items=1 ppid=14201 pid=14202 auid=admin_alice uid=testuser gid=testuser euid=testuser suid=testuser fsuid=testuser egid=testuser sgid=testuser fsgid=testuser tty=pts1 ses=12 comm=cat exe=\/usr\/bin\/cat subj=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023 key=unauthorized_file_access\n<\/code><\/pre>\n
    Deconstructing the Audit Record for Incident Response<\/h3>\n
    Notice how thoroughly the record exposes the incident details:<\/p>\n