This module modifies core system authentication mechanisms. Incorrect configuration or bugs may lead to system lockout or authentication failures. Always test in a safe environment first and keep an emergency root terminal open during development.
The aegis-pam module provides integration with PAM (Pluggable Authentication Modules) - a universal authentication framework for Unix/Linux systems.
PAM serves as a standard interface mediating between applications and authentication mechanisms, enabling modular and configurable access control.
- Unified authentication mechanism
- Compatibility with existing PAM infrastructure
- Flexible security policy configuration
- Support for various authorization methods
- Development mode with enhanced logging
- Emergency terminal fallback
The system consists of three main components:
-
PAM Module (
pam_aegis.so)- Installed in the PAM system
- Intercepts authentication requests
- Lightweight and fast processing
- Communicates with the agent via Unix socket
- Handles basic authentication flow
- Logs authentication attempts
- Supports development mode with detailed logging
-
Aegis Agent (
aegis_pam_agent)- Background service managed by systemd
- Handles complex authentication logic
- Manages security policies
- Provides logging and monitoring
- Automatic restart capability
- Processes authentication requests from PAM module
- Maintains persistent state
- Manages user sessions
-
Configuration Layer
- PAM stack configuration in /etc/pam.d/
- Agent configuration in /etc/aegis/
- Security policy definitions
- Development mode settings
The module activates during:
- Execution of sudo command
- User session login
- User switching (su)
- Screen unlock
- Any PAM-aware application authentication
- Linux system with PAM framework
- Root privileges for installation
- systemd for service management
- C++20 compatible compiler
- meson build system
-
Development Mode (
./install.sh dev)- Enables debug logging
- Opens emergency root terminal
- Installs in debug configuration
- Creates log file at /tmp/aegis_pam_dev.log
-
Sudo Mode (
./install.sh sudo)- Installs for sudo authentication only
- Configures PAM stack for sudo
- Starts agent service
- Production configuration
-
Global Mode (
./install.sh global)- System-wide installation
- Modifies common-auth
- Full PAM integration
- Production configuration
install.sh- Main installation scriptuninstall.sh- Removes module and restores configurationtests/run_tests.sh- Executes test suitescripts/backup_pam.sh- Creates PAM config backup
- Authentication request received
- Username obtained from PAM
- Request logged (if in dev mode)
- Communication with agent via socket
- Response processing
- Authentication result returned
- Starts as systemd service
- Listens on Unix socket
- Processes authentication requests
- Manages user sessions
- Handles security policies
- Maintains audit log
Development mode provides:
- Enhanced logging at
/tmp/aegis_pam_dev.log - Real-time monitoring tools
- Emergency root terminal
- Detailed authentication tracking
-
System Access
- Always maintain an emergency root terminal during development
- Keep original PAM configuration backups
- Test in a safe environment first
-
Monitoring
- Check logs for unauthorized access attempts
- Monitor agent status regularly
- Review authentication patterns
-
Recovery
- Emergency terminal provides system access if PAM fails
- Uninstall script restores original configuration
- Backup of original PAM settings is maintained
This project is licensed under GNU General Public License v3.0 - see the LICENSE file for details.
Before contributing:
- Test all changes in an isolated environment
- Maintain comprehensive logging
- Document security implications
- Follow secure coding practices
- Include test cases
In case of authentication issues:
- Use the emergency terminal (if available)
- Boot in single-user mode
- Execute the uninstall script
- Restore original PAM configuration
Remember: PAM modifications can lock you out of your system. Always maintain a backup authentication method.