chore: add MIT license and enhance README with detailed role information and usage examples

Author: leucos

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 DevopsWorks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,11 +1,202 @@
-# ansible-auditship
+# Ansible Role: auditship
 
-Installs auditship (https://gitlab.com/devopsworks/tools/auditship) to ship
-audit logs to Fluentd.
+[![CI](https://github.com/devops-works/ansible-auditship/workflows/CI/badge.svg)](https://github.com/devops-works/ansible-auditship/actions?query=workflow%3ACI)
 
-This role does not check if v is already installed and overrides
-existing binary (no way to check version in v yet).
+An Ansible role for installing and configuring [auditship](https://gitlab.com/devopsworks/tools/auditship), a tool that ships Linux audit logs to Fluentd endpoints in real-time.
 
-## Variables
+## Features
+
+- Automatically downloads the latest auditship binary from GitLab releases
+- Configures auditship as an auditd plugin for real-time log shipping
+- Sets up log rotation to prevent disk space issues
+- Supports multiple Linux distributions (Ubuntu, Debian)
+- Idempotent installation with force reinstall option
+
+## Requirements
+
+- Ansible >= 2.4
+- Target systems must have `auditd` installed and running
+- Internet connectivity for downloading auditship binary and configuration files
+- Root privileges on target systems
+
+## Role Variables
+
+### Required Variables
 
 - `auditship_fluent_url`: URL to Fluentd endpoint (default: `fluent://127.0.0.1:24224`)
+
+### Optional Variables
+
+- `auditship_force_install`: Forces reinstallation even if binary exists (default: `false`)
+
+### Example Variable Configuration
+
+```yaml
+auditship_fluent_url: "fluent://log-collector.example.com:24224"
+auditship_force_install: true
+```
+
+## Dependencies
+
+None.
+
+## Example Playbook
+
+### Basic Usage
+
+```yaml
+- hosts: servers
+  become: true
+  roles:
+    - devopsworks.auditship
+```
+
+### With Custom Fluentd Endpoint
+
+```yaml
+- hosts: servers
+  become: true
+  vars:
+    auditship_fluent_url: "fluent://log-server.company.com:24224"
+  roles:
+    - devopsworks.auditship
+```
+
+### Force Reinstallation
+
+```yaml
+- hosts: servers
+  become: true
+  vars:
+    auditship_force_install: true
+  roles:
+    - devopsworks.auditship
+```
+
+## Installation
+
+### From Ansible Galaxy
+
+```bash
+ansible-galaxy install devopsworks.auditship
+```
+
+### From Git Repository
+
+```bash
+ansible-galaxy install git+https://github.com/devops-works/ansible-auditship.git
+```
+
+## What This Role Does
+
+1. **Version Detection**: Queries GitLab API to find the latest auditship release
+2. **Binary Download**: Downloads the compressed auditship binary for Linux AMD64
+3. **Installation**: Extracts and installs the binary to `/usr/local/bin/auditship`
+4. **Plugin Configuration**: Creates auditd plugin configuration in `/etc/audit/plugins.d/auditship.conf`
+5. **Log Rotation**: Downloads and installs logrotate configuration to `/etc/logrotate.d/auditship`
+
+## File Locations
+
+- **Binary**: `/usr/local/bin/auditship`
+- **Plugin Config**: `/etc/audit/plugins.d/auditship.conf`
+- **Log Rotation**: `/etc/logrotate.d/auditship`
+
+## Supported Platforms
+
+- Ubuntu (all versions)
+- Debian (all versions)
+
+## Testing
+
+This role includes comprehensive testing using Molecule with Podman driver.
+
+### Prerequisites
+
+```bash
+pip install -r requirements.txt
+```
+
+### Run Tests
+
+```bash
+# Run all tests
+make test
+
+# Run linting only
+make lint
+
+# Run syntax check
+make syntax
+```
+
+### Test Platforms
+
+- Ubuntu 24.04
+- Debian 11
+- Debian 12
+
+## Development
+
+### Setup Development Environment
+
+1. Clone the repository
+2. Install dependencies: `make install`
+3. Run tests: `make test`
+
+### Available Make Targets
+
+- `make help` - Show available commands
+- `make install` - Install Python dependencies
+- `make lint` - Run all linting tools
+- `make test` - Run molecule tests
+- `make clean` - Clean up test artifacts
+- `make syntax` - Check Ansible syntax
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Internet Connectivity**: Ensure target systems can reach GitLab for downloading binaries
+2. **Auditd Service**: Verify auditd is installed and running before applying this role
+3. **Permissions**: Role requires root privileges for installation and configuration
+
+### Verification
+
+After running the role, verify installation:
+
+```bash
+# Check binary exists and is executable
+ls -la /usr/local/bin/auditship
+
+# Test auditship version
+/usr/local/bin/auditship -version
+
+# Verify plugin configuration
+cat /etc/audit/plugins.d/auditship.conf
+
+# Check auditd is using the plugin
+sudo service auditd status
+```
+
+## License
+
+MIT
+
+## Author Information
+
+This role was created by [DevopsWorks](https://devopsworks.io/).
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Run the test suite: `make test`
+6. Submit a pull request
+
+## Links
+
+- [auditship project](https://gitlab.com/devopsworks/tools/auditship)
+- [Issue tracker](https://github.com/devops-works/ansible-auditship/issues)
+- [DevopsWorks](https://devopsworks.io/)