{"id":19281774,"url":"https://github.com/scality/ghaudit","last_synced_at":"2026-05-18T14:09:02.807Z","repository":{"id":43094016,"uuid":"291964764","full_name":"scality/ghaudit","owner":"scality","description":"Github organisation security auditing tool","archived":false,"fork":false,"pushed_at":"2022-04-21T14:26:44.000Z","size":418,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-02-23T22:21:09.907Z","etag":null,"topics":["github","it","security","security-audit","security-compliance"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scality.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"docs/CODEOWNERS","security":"docs/SECURITY.md","support":null}},"created_at":"2020-09-01T10:15:51.000Z","updated_at":"2024-08-28T06:58:22.000Z","dependencies_parsed_at":"2022-08-19T12:10:41.875Z","dependency_job_id":null,"html_url":"https://github.com/scality/ghaudit","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/scality/ghaudit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scality%2Fghaudit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scality%2Fghaudit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scality%2Fghaudit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scality%2Fghaudit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scality","download_url":"https://codeload.github.com/scality/ghaudit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scality%2Fghaudit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33180375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"ssl_error","status_checked_at":"2026-05-18T09:27:28.300Z","response_time":71,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","it","security","security-audit","security-compliance"],"created_at":"2024-11-09T21:24:08.132Z","updated_at":"2026-05-18T14:09:02.783Z","avatar_url":"https://github.com/scality.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ghaudit\n\nGithub organisation security auditing tool.\n\nGhaudit verifies the state of a github organisation for compliance against a\nreference configuration for access control. Properties that can be checked now:\n\n * repository sharing (private, public, or internal)\n * effective repository access\n * organisation teams, with their hierarchy and accesses\n * organisation team members with roles\n * organisation members with roles\n * repository branch protection rules\n\nGhaudit is caching a snapshot state of the github organisation in order to make\naudit results reproducible.\n\nGhaudit is only for auditing: ghaudit can not run write operations for applying\nremediation.\n\n## Installation\n\nghaudit requires python 3.8 or later.\n\n\n```shell\ngit clone https://github.com/scality/ghaudit\ncd ghaudit\npip install .\n```\n\n## Configuration\n\nGhaudit relies on 3 configuration files:\n\n * a `user map.yml` file describing a mapping between github logins and emails\n * an `organisation.yml` file describing the expected organisation structure\n * a `policy.yml` file describing the policy of access to the github\n   organisation resources\n\n### Organisation configuration file\n\nThis configuration file describes the expected structure or the organisation\nmembers and teams hierarchy, as well as the github organisation owners.\n\nSee the [example configuration file](example/organisation.yml) to find out how\nto define an organisation structure.\n\nThe user map is stored in an XDG compliant user configuration directory by\ndefault:\n\n * `$XDG_CONFIG_HOME/ghaudit/organisation.yml` if `XDG_CONFIG_HOME` is set and\n   non empty.\n * `$HOME/ghaudit/organisation.yml` otherwise\n\nAn alternative path to the configuration file can be specified with `--config`.\n\n### User map configuration\n\nIn order to help managing ghaudit configuration and policy in a corporate\nenvironment, ghaudit relies on emails as much as possible. However a github\naccount email may not be trusted. This is why ghaudit relies on a configuration\nfile to make the relationship between accounts and emails.\n\nSee the [example configuration file](example/user%20map.yml) to find out how to\ndefine the user map.\n\nThe user map is stored in an XDG compliant user configuration directory by\ndefault:\n\n * `$XDG_CONFIG_HOME/ghaudit/user map.yml` if `XDG_CONFIG_HOME` is set and non\n   empty.\n * `$HOME/ghaudit/user map.yml` otherwise\n\nAn alternative path to the user map can be specified with `--user-map`.\n\n### Policy Configuration\n\nThe policy describes the desired access rules and security controls over the\ngithub resources. Supported features are:\n\n * repository visibility\n * rules of access:\n   * access mapping between lists of teams and repositories\n   * branch protection rules to apply to repositories\n * exceptions to the rules: direct user access to team, including external\n   collaborators\n\nghaudit supports 2 mode of branch protection rules checking:\n\n * a baseline mode: the described branch protection rules list the minimal\n   restrictions to apply to branches for the policy to pass\n * a strict mode: the described branch protection rules represent the exact\n   match of restrictions and authorisations for the policy to pass\n\nSee the [example configuration file](example/policy.yml) to find out how\nto define a policy document.\n\nghaudit looks in the XDG compliant user configuration directory for the policy\nby default:\n\n * `$XDG_CONFIG_HOME/ghaudit/policy.yml` if `XDG_CONFIG_HOME` is set and\n   non empty.\n * `$HOME/ghaudit/policy.yml` otherwise\n\nAn alternative path to the policy can be specified with `--policy`.\n\n### Github credentials\n\nGithub API credentials are required in order to run ghaudit. The following API\nscopes are required:\n\n * user/read:user\n * admin:org/read:org\n * repo\n\nWithout read only admin access, branch protection rules can not be tested and\nhidden teams will not be seen by ghaudit.\n\nSee also the [github\ndocumentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)\nabout personal access token creation.\n\nThe personal access token must be stored in a\n[pass](https://www.passwordstore.org) store, with `ghaudit/github-token` as\nname by default:\n\n```shell\n$\u003e pass insert ghaudit/github-token\nEnter password for ghaudit/github-token:\nRetype password for ghaudit/github-token:\n#\u003e\n```\n\nAlternatively, if you do not have pass installed, you can use\n[passpy](https://pypi.org/project/passpy/) instead, which is included with\nghaudit:\n\n```shell\n$\u003e passpy insert ghaudit/github-token\nEnter password for ghaudit/github-token:\nRepeat for confirmation:\n#\u003e\n```\n\nThe name of the token can be specified using the option `--token-pass-name`, if\nthe default pass path is not used. See `ghaudit cache refresh --help` for more\ndetails.\n\n## Usage\n\nghaudit is split in multiple sub commands which can themselves have sub\ncommands. All commands have their own detailed usage:\n\n```shell\n$\u003e ghaudit\nUsage: ghaudit [OPTIONS] COMMAND [ARGS]...\n\n  Github organisation security auditing tool.\n\nOptions:\n  -c, --config TEXT\n  --user-map TEXT\n  --policy TEXT\n  -h, --help         Show this message and exit.\n\nCommands:\n  cache       Cache manipulation commands.\n  compliance  Compliance tests against policies and configuration.\n  org         Cached state views.\n  stats       Show some statistics about the cached state.\n  user        Cached state view for github users.\n  usermap     Login to email and email to loginUsage: ghaudit [OPTIONS] COMMAND [ARGS]...\n$\u003e ghaudit cache\nUsage: ghaudit cache [OPTIONS] COMMAND [ARGS]...\n\n  Cache manipulation commands.\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  path\n  refresh\n```\n\n### Typical workflow\n\nA typical workflow using ghaudit consists of:\n\n * a cache refresh\n * a compliance check run\n * investigating\n\n```shell\n$\u003e ghaudit cache refresh\n[redacted]\nvalidating cache\npersisting cache\n$\u003e ghaudit compliance check all\n[errors]\n```\n\nInvestigating the state of the organisation can be done by using the following\ncommand groups:\n\n * `ghaudit org`: show information about the state of the audited organisation\n * `ghaudit user`: show information about a user if the user is related to the\n   organisation or if they are a collaborator to a repository owned by the\n   organisation\n\nMost investigation commands have output formatting mode that can be specified\nusing the `--format` option.\n\n## Audit scope\n\nghaudit will implicitly audit all repositories that are not forks or not\narchived by default. To silence compliance errors for some repositories,\nrepositories can be explicitly excluded in the policy configuration. See also\nthe [example file](example/policy.yml) for the policy configuration.\n\n## Security\n\nIf you found a security vulnerability in ghaudit, please refer to our security\npolicy for instruction on how to report it. The Security policy can be found\nhere: [docs/SECURITY.md](docs/SECURITY.md).\n\n## Contributing\n\nContributing guidelines can be found here:\n[docs/contributing.md](docs/contributing.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscality%2Fghaudit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscality%2Fghaudit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscality%2Fghaudit/lists"}