grove.connectors.github package

Github connectors for Grove.

Submodules

grove.connectors.github.api module

GitHub API client.

As PyGitHub does not currently support the Audit API, this client has been created in the interim.

class grove.connectors.github.api.Client(hostname: str = 'api.github.com', scope: str = 'orgs', identity: str | None = None, token: str | None = None, retry: bool | None = True)

Bases: object

get_audit_log(phrase: str | None = None, include: str | None = 'all', order: str | None = 'asc', cursor: str | None = None) → AuditLogEntries

Fetches a list of audit logs which match the requested filter and event type.

Parameters:

• phrase – Search phrase to use when filtering logs.

• include – Event type to return (web, git, or all).

• order – Order to return results (asc, desc).

• cursor – Cursor to use when fetching results. Supersedes other parameters.

Returns:

AuditLogEntries object containing a pagination cursor, and log entries.

grove.connectors.github.audit_log module

GitHub Audit connector for Grove.

class grove.connectors.github.audit_log.Connector(config: ConnectorConfig, context: Dict[str, str])

Bases: BaseConnector

LOG_ORDER = 'CHRONOLOGICAL'

NAME = 'github_audit_log'

POINTER_PATH = '"@timestamp"'

collect()

Collects all logs from the GitHub Audit API.

This will first check whether there are any pointers cached to indicate previous collections. If not, the last week of data will be collected.

property delay

Defines the amount of time to delay collection of logs (in minutes).

This is used to allow time for logs to become ‘consistent’ before they are collected. This is required as Github backfills log entries but unfortunately do not provide any guidance around ‘lag’ time, or guarantees on availability and delivery.

As a result of these constraints, this value is configurable to allow operators to preference consistency over speed of delivery, and vice versa. For example, a delay of 20 would instruct Grove to only collect logs after they are at least 20 minutes old.

This defaults to 0 (no delay).

Returns:

The “delay” component of the connector configuration.

property fqdn

Fetches the configured Github API FQDN, or the default (SaaS).

Returns:

The “fqdn” component of the connector configuration.

property scope

Fetches the configured Github scope.

This is used to control whether the connector should collect logs for a Github enterprise, or an organisation. This defaults to “orgs”.

Returns:

The “scope” component of the connector configuration.