sheriff

README

.. image:: https://pkg.go.dev/badge/github.com/frontierdigital/sheriff.svg
    :target: https://pkg.go.dev/github.com/frontierdigital/sheriff
.. image:: https://github.com/frontierdigital/sheriff/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/frontierdigital/sheriff/actions/workflows/ci.yml

=======
Sheriff
=======

Sheriff is a command line tool to manage **Azure role-based access control (Azure RBAC)**
and **Microsoft Entra Priviliged Identity Management (Microsoft Entra PIM)** using desired state configuration.

.. contents:: Table of Contents
    :local:

-----
About
-----

~~~~~~~
Sheriff
~~~~~~~

Sheriff has been built to enable the management of Azure RBAC and Microsoft Entra PIM configuration
via YAML/JSON files. Although some of its functionality overlaps with the AzureRM provider
for Terraform, the Terraform implementation lacks coverage for some key features required
to operate PIM effectively, including role management policies.

Where Terraform also requires state to be maintained, Sheriff is different: it uses Azure APIs as it's
only source of truth, and ensures configuration is always consistent with the desired state, regardless
of how that configuration was set. For example, if a user manually adds a role assignment that isn't
present in the desired state YAML configuration, Sheriff will remove it.

Sheriff is designed to be used as part of a CI/CD pipeline.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Azure role-based access control (Azure RBAC)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Azure role-based access control (Azure RBAC) helps you manage who has access to
Azure resources, what they can do with those resources, and what areas they have access to.

See `What is Azure role-based access control (Azure RBAC)? <https://learn.microsoft.com/en-us/azure/role-based-access-control/overview>`_ for more information.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Microsoft Entra Privileged Identity Management (Microsoft Entra PIM)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Microsoft Entra Privileged Identity Management (PIM) is a service in Microsoft Entra ID that
enables you to manage, control, and monitor access to important resources in your organization.
These resources include resources in Microsoft Entra ID, Azure, and other Microsoft Online Services
such as Microsoft 365 or Microsoft Intune.

See `What is Microsoft Entra Privileged Identity Management? <https://learn.microsoft.com/en-gb/entra/id-governance/privileged-identity-management/pim-configure?WT.mc_id=Portal-Microsoft_Azure_PIMCommon>`_ for more information.

--------
Download
--------

~~~~~~~
Release
~~~~~~~

Binaries and packages of the latest stable release are available at `https://github.com/frontierdigital/sheriff/releases <https://github.com/frontierdigital/sheriff/releases>`_.

~~~~~~~~~
Extension
~~~~~~~~~

The Sheriff extension for Azure DevOps is available from `Visual Studio Marketplace <https://marketplace.visualstudio.com/items?itemName=frontierdigital.sheriff>`_, which will automatically install Sheriff via a task.

-------------
Configuration
-------------

~~~~~~~~~~~~~~~
Azure Resources
~~~~~~~~~~~~~~~

.. code:: bash

  groups/
    <group name>.yml
    ...
  rulesets/
    <ruleset name>.yml
    ...
  users/
    <user upn>.yml
    ...

Configuration of role assigments is managed via YAML files per group and/or user, in which both active and eligible role assignments are defined.

.. code:: yaml

  active:
    subscription: []
    resourceGroups: {}
    resources: {}
  eligible:
    subscription: []
    resourceGroups: {}
    resources: {}


~~~~~~~~~~~~~~~~~~~~~
Microsoft Entra roles
~~~~~~~~~~~~~~~~~~~~~

*Coming soon...*

~~~~~~
Groups
~~~~~~

*Coming soon...*

-----
Usage
-----

.. code:: bash

  $ sheriff --help
  Sheriff is a command line tool to manage Azure role-based access control (RBAC) and Microsoft Entra Priviliged Identity Management (PIM) configuration declaratively

  Usage:
    sheriff
    sheriff [command]

  Available Commands:
    apply       Apply config
    completion  Generate the autocompletion script for the specified shell
    help        Help about any command
    plan        Plan changes
    validate    Validate config
    version     Output version information

  Flags:
    -h, --help   help for sheriff

  Use "sheriff [command] --help" for more information about a command.

~~~~~~~~~~~~~~~
Azure Resources
~~~~~~~~~~~~~~~

Plan
~~~~

.. code:: bash

  $ sheriff plan azurerm \
      --config-dir <path to AzureRM config> \
      --subscription-id <subscription ID>

Apply
~~~~~

.. code:: bash

  $ sheriff apply azurerm \
      --config-dir <path to AzureRM config> \
      --subscription-id <subscription ID>

~~~~~~~~~~~~~~~~~~~~~
Microsoft Entra roles
~~~~~~~~~~~~~~~~~~~~~

*Coming soon...*

~~~~~~
Groups
~~~~~~

*Coming soon...*