StackGuardian / StackGuardian/tirith

feat(provider): repo-metadata checks and a GitHub metadata collector

Open
#310 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
165
Forks
42
Avg merge
1d 3h
Merged PRs (30d)
11

Description

Repo posture — is the repository private, is branch protection on, are reviews required, is secret
scanning enabled — is checkable by nothing in Tirith today, yet it is the same policy shape as
everything else: a JSON document and typed assertions. The engine needs no change — policies over
SECURITY-INSIGHTS.yml (a YAML file in the repository) already work with the existing json
provider.

Proposal. Two halves:

  1. Collectortirith github collect (token via env/stdin, like --api-key -) fetching a
    keyed bag of GitHub REST responses — repository, branch_protection.<branch>, rulesets,
    workflow_permissions, actions_permissions, organization, code_security_config — into one
    JSON document, field names exactly as GitHub's published OpenAPI defines them, with a
    404-fallback convention ({"http_status": 404, …}) so "branch not protected" is expressible
    with existing conditions. GitLab later, same envelope.
  2. Predefined checks — a starter pack over that document: repo is private, default branch
    protected, force-push disabled, reviews ≥ 1, admins enforced, secret scanning + push protection
    on, Actions workflow permissions read-only. Also: Tirith itself is configured, and configured
    correctly, in the repo's CI pipelines.
    Severity-tagged so --fail-on-severity gates them.

Existing open-source declarative rule sets over the GitHub API shape (~180 rules combined)
translate almost by transcription once the document shape is GitHub's.
Note: some checks may end up platform-side rather than OSS; that split is an open product decision.

Acceptance. tirith github collect | tirith -policy-path packs/repo-metadata … fails on a
public repo with an unprotected default branch and passes after protection is enabled; the 404
fallback is covered by a fixture; the collector never writes the token into the document.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the tirith github collect entry point and review the existing JSON provider and SECURITY-INSIGHTS.yml policy flow. Use the named GitHub REST response keys and the packs/repo-metadata checks as the scope, with a fixture covering the 404 fallback. Done means the acceptance pipeline fails and passes as described, and the token is absent from the collected document.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, python
Domain
api, cli, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.