# GitHub

> How Cloak Watch's read-only GitHub connection checks your repositories and account for worm activity, malicious lockfiles and risky settings, what it reads and what it keeps.

Source: https://docs.subcloak.com/cloak-watch/github/

Added in Cloak Watch 1.2.0.

The **GitHub** section, under **Beyond this Mac** in the sidebar, checks your GitHub repositories and account, including repositories that aren't cloned on this Mac: lockfiles against the feed, workflows, settings, and signs that a worm used your account. Access is read-only, and Watch talks to GitHub straight from your Mac: Subcloak never sees your token, your repository names or what Watch finds.

> **Coming soon:**
> Connecting GitHub needs Subcloak's GitHub App. Until it's available, the GitHub screen shows **Coming soon** where **Connect GitHub…** would be, and nothing is sent to GitHub. Watch keeps checking the workflows and lockfiles in your local clones, on this Mac, and the screen shows how many repositories it found there. The rest of this page describes how GitHub checks work once you can connect.

*[Screenshot: The GitHub screen: Connect GitHub with Read-only access to your repositories and account, Coming soon, Found on this Mac: 4 repositories from ada-park and shopapp-org, and What Watch checks: lockfiles and workflows, worm activity on your account, workflow runs, repository settings and your account's keys]*

## Connect GitHub

1. Open **GitHub** in the sidebar and click **Connect GitHub…**.

2. Watch shows a code. Click **Copy Code**, then **Open GitHub**, and enter the code on GitHub's device page.

   Only approve if GitHub's page names Cloak Watch, and only enter a code this window showed you. The sheet says how long the code works.

3. On GitHub, approve Cloak Watch and choose which repositories it can read.

4. Back in Watch, the screen shows **Signed in as** your account, each installation with **All repositories** or **Selected repositories**, and starts checking.

Choose **All repositories** if you can. With **Only select repositories**, new repositories, such as ones a worm creates, aren't visible, though Watch still checks your account's public repositories and events. An organization's repositories need an owner of the organization to approve the app. Some settings are only visible to a repository's admins.

**Choose Repositories on GitHub…** changes the selection later.

> **Codes from someone else:**
> Anyone can start a GitHub sign-in with Cloak Watch's public app ID and send you the code. Never enter a code you didn't see in Watch's own window. Cloak Watch only ever asks for read-only access.

## What Watch checks

Once a day while Watch is open, and when you click **Check Now**. Everything is matched on your Mac, and when the feed learns about a new malicious package or incident, Watch matches what it last read from GitHub at once, without asking GitHub again. Findings go to the [Inbox](https://docs.subcloak.com/cloak-watch/inbox/).

| Card | Tier | What |
|---|---|---|
| [GH-1](https://docs.subcloak.com/cloak-watch/detections/#gh-1) | Act now when the repository has workflows; Review otherwise | A known-malicious package version pinned in a repository's lockfile |
| [GH-2](https://docs.subcloak.com/cloak-watch/detections/#gh-2) | Act now | Worm activity on your account: repositories named like s1ngularity's or Shai-Hulud's, a self-hosted runner named `SHA1HULUD`, or the worms' workflows |
| [GH-3](https://docs.subcloak.com/cloak-watch/detections/#gh-3) | Review; Act now for three in a day or with other worm signs | A private repository made public |
| [GH-4](https://docs.subcloak.com/cloak-watch/detections/#gh-4) | Act now | A run of a workflow an incident names, since the incident began: treat it as a leak |
| [GH-5](https://docs.subcloak.com/cloak-watch/detections/#gh-5) | Review | A workflow on GitHub matches a headline's workflow check |
| [GH-6](https://docs.subcloak.com/cloak-watch/detections/#gh-6) | Review | A public repository runs workflows on a self-hosted runner |
| [GH-7](https://docs.subcloak.com/cloak-watch/detections/#gh-7) | Review; FYI | Webhooks over `http`, without certificate checks, or to a request-capture service; webhooks without a secret |
| [GH-8](https://docs.subcloak.com/cloak-watch/detections/#gh-8) | Review; FYI | Deploy keys that can push, added in the last 14 days, or older |
| [GH-9](https://docs.subcloak.com/cloak-watch/detections/#gh-9) | FYI | Outside collaborators who can push |
| [GH-10](https://docs.subcloak.com/cloak-watch/detections/#gh-10) | FYI | Unprotected default branches on public or shared repositories |
| [GH-11](https://docs.subcloak.com/cloak-watch/detections/#gh-11) | FYI | Actions settings: a write token by default, workflows that approve pull requests, fork workflows without approval |
| [GH-12](https://docs.subcloak.com/cloak-watch/detections/#gh-12) | Review | An SSH, signing or GPG key added to your account in the last 14 days that isn't on this Mac |

The workflow rules Watch runs on your local clones ([REPO-1 to REPO-7](https://docs.subcloak.com/cloak-watch/detections/#repositories-and-ci-repo) and PKG-9) also run on GitHub's copies, titled "On GitHub: …".

## What it reads and keeps

**Read-only.** Watch only reads from GitHub: repository metadata, files such as lockfiles and workflows, Actions runs and settings, repository settings and webhooks, and your account's SSH, signing and GPG keys. It never changes anything on GitHub. GitHub shows the exact permissions when you approve Cloak Watch.

**What leaves your Mac.** Watch talks to GitHub directly: to `github.com` when you connect (the code) and to renew the token, which GitHub limits to 8 hours, and to `api.github.com` for read-only requests. These follow your Mac's proxy settings, as your browser does. When a proxy is set, the screen says so, because a proxy that inspects HTTPS can see the token. Nothing goes to Subcloak.

**What stays on your Mac.** The token is kept in this Mac's Keychain, on this device only, never synced. In files only you can read, Watch keeps what it parsed from GitHub's answers, such as package versions from lockfiles, facts about each workflow (the actions it uses, its triggers, the hosts it names), webhook hosts and repository settings, and the few fields it needs to ask GitHub again cheaply. It never keeps file contents, webhook URLs (Slack and Discord keep their secret in the URL), or your profile details such as your name and email. Unchanged files aren't downloaded again.

**What GitHub sees.** GitHub, and your organizations' owners, can see that you authorized Cloak Watch.

## Limits

- Watch sees only repositories where Cloak Watch is installed, up to 300, and run history and events from the last 90 days.
- Watch stops when fewer than 1,000 of your GitHub API requests remain this hour, so your other tools keep working ("Paused to leave GitHub requests for your other tools"), and uses conditional requests, which don't count against the limit.
- GitHub has no API for your personal security log or your personal access tokens, so Watch can't check those.

## Disconnect

Click **Disconnect…**. Watch removes the token from this Mac's Keychain and forgets what it read. Watch can't revoke its own authorization on GitHub: choose **Disconnect and Open GitHub** to open GitHub's Applications settings and revoke Cloak Watch there too.

## Related

  - [Footprint](https://docs.subcloak.com/cloak-watch/footprint/): The repositories this Mac's clones point at.
  - [Detection catalogue](https://docs.subcloak.com/cloak-watch/detections/#github-gh): GH-1 to GH-12.
  - [What leaves your Mac](https://docs.subcloak.com/cloak-watch/settings/#what-leaves-your-mac): The GitHub row in Settings › Privacy.