Metadata-Version: 2.1
Name: github-vulnerability-exporter
Version: 1.5.2
Summary: UNKNOWN
Home-page: https://github.com/ZeitOnline/github_vulnerability_exporter
Author: Wolfgang Schnerring
Author-email: wolfgang.schnerring@zeit.de
License: BSD
Platform: UNKNOWN
License-File: LICENSE
Requires-Dist: prometheus-client
Requires-Dist: requests
Requires-Dist: setuptools

==============================================
Prometheus GitHub vulnerability alert exporter
==============================================

This package exports the `Security Vulnerability Alerts`_ from GitHub for all repositories of an organization as `Prometheus`_ metrics.

.. _`Security Vulnerability Alerts`: https://help.github.com/en/categories/managing-security-vulnerabilities
.. _`Prometheus`: https://prometheus.io


Usage
=====

Configure API token
-------------------

You'll need to provide an access token with scope ``repo`` to access the GitHub API.
See the `GitHub documentation`_ for details.

.. _`GitHub documentation`: https://developer.github.com/v4/guides/forming-calls/#authenticating-with-graphql


Start HTTP service
------------------

Start the HTTP server like this::

    $ GITHUB_AUTHTOKEN=MYTOKEN GITHUB_OWNER=MyGitHubOrgOrUser github_vulnerability_exporter --host=127.0.0.1 --port=9597

Pass ``--ttl=SECONDS`` to cache GitHub API results for the given time or -1 to disable (default is 600).
Prometheus considers metrics stale after 300s, so that's the highest scrape_interval one should use.
However it's usually unnecessary to hit the API that often, since the vulnerability alert information does not change that rapidly.

Pass ``--forked`` if you want to include forked repositories (not sure if they actually receive vulnerability alerts, though).


Configure Prometheus
--------------------

::

    scrape_configs:
      - job_name: 'vulnerabilities'
        scrape_interval: 300s
        static_configs:
          - targets: ['localhost:9597']

We export one metric, a gauge called ``github_vulnerability_alerts``,
with labels ``{repository="MyGitHubOrgOrUser/my-repository-name, status="active|dismissed"}``.

Additionally, a ``ghvuln_scrape_duration_seconds`` gauge is exported.


CHANGES
=======


1.5.2 (2023-04-11)
------------------

- Brown-bag release


1.5.1 (2023-04-11)
------------------

- Interpret "dismissedAt: unknown" as dismissed, not active


1.5.0 (2019-06-07)
------------------

- Add in-memory caching so we don't have to hit the API on each scrape


1.4.0 (2019-06-07)
------------------

- Support collecting data for repositories of either an organization or a user


1.3.0 (2019-06-07)
------------------

- Make listen host configurable


1.2.0 (2019-06-07)
------------------

- Add `status` label to differentiate between active and dismissed alerts


1.1.0 (2019-06-07)
------------------

- Allow configuring via environment variables as well as command line parameters


1.0.1 (2019-06-07)
------------------

- Increase repository query batch size.


1.0.0 (2019-06-06)
------------------

- First release.


