πŸ›‘οΈ Assets Guardian

Audit identities, access rights, and security compliance across all solutions in your Information System from a single place, with all data consolidated into one unified format regardless of the source.

Version License: GPLv3 Python Documentation

Assets Guardian is a modular, multi-source, multi-instance Identity and Access Management (IAM) governance tool. It audits identities, access rights, and security compliance across every solution in your IT environment, all from one place, with data consolidated into a single unified format regardless of the source.

  • Modular Architecture: Add, remove, or create your own custom plugins without ever modifying the core codebase.

  • Comprehensive Reporting: Automatically generates a detailed Excel IAM inventory/register and PDF audit reports.

  • Rule-Based Engine: Extensible compliance and rule engine for evaluating access policies.

  • Local or SharePoint Storage: Read configuration from, and publish reports to, a SharePoint document library instead of the local filesystem.

  • Email Notifications: Send the audit report to a list of recipients at the end of a run.

πŸ”Œ Available Plugins

Each plugin is self-contained and only activated when explicitly declared in config.yml. Every plugin supports multiple instances of the same platform.

Plugin

Status

Authentication

Audited data

GitLab

βœ… Available

Personal Access Token (Bearer)

Users, groups, projects & access rights

Dolibarr

βœ… Available

API key (DOLAPIKEY)

Users, groups & access rights

Microsoft 365

βœ… Available

Microsoft Graph, app-only OAuth2 (tenant / application ID / secret)

Users (MFA, sign-in activity), groups, directory roles, app registrations & licenses

πŸ’‘ Tip: Your platform isn’t listed? Adding a connector never touches the core engine, see the Plugin Development Guide.

πŸš€ Quick Start

The fastest way to use Assets Guardian is to install it once as a global command, then run it from any audit folder, no uv run prefix, no virtual environment to activate. This mode targets operators, auditors, and IT teams who consume the tool.

Prerequisites:

  • Python 3.13+: runtime

  • uv: builds & installs the command

  • make: runs the install shortcuts

1. Install the command

Install the assets-guardian command into an isolated environment on your PATH:

git clone git@github.com:apizee/assets-guardian.git
cd assets-guardian/
make install

Verify it from anywhere:

assets-guardian --version

πŸ’‘ Tip: If your shell can’t find the command, run uv tool update-shell and restart your terminal.

2. Prepare an audit folder

The installed command resolves every file relative to the directory you launch it from. Create a dedicated folder for your audit and drop your configuration into it:

my-iam-audit/
β”œβ”€β”€ config/         # config.yml, template.config.yml, rules_config.yml, employees.json, excel/pdf styling
β”œβ”€β”€ .env            # plugin credentials (optional, depends on the plugins you enable)
β”œβ”€β”€ logs/           # rotating log files (auto-created on first run)
└── outputs/        # generated Excel & PDF reports (auto-created on first run)

⚠️ Warning: Keep template.config.yml next to config.yml. It is not a backup: Assets Guardian validates your configuration against it at startup, and the run fails without it.

πŸ’‘ Tip: The quickest way to bootstrap it is to copy the repository’s config/ directory, rename each template.* file (drop the template. prefix), and copy .env.template to .env. See Getting Started for the full configuration reference.

3. Run it

From inside your working directory, call the commands directly:

cd my-iam-audit
assets-guardian --help          # show all available flags and commands
assets-guardian check           # diagnostic of config, connectivity & permissions
assets-guardian sync            # build / update the Excel IAM inventory
assets-guardian audit           # evaluate the rules & generate the PDF report
assets-guardian script <name>   # run a custom power-user script from scripts/ (advanced)

πŸ’‘ Tip: Upgrade later with make upgrade, and remove the command entirely with make uninstall.

πŸ“œ License

This project is licensed under the GNU General Public License v3.0 (GPLv3). See the LICENSE.txt file for the full text.