Add support for fine grained acces token (#497)

Co-authored-by: Ved misra <47312748+misraved@users.noreply.github.com>

Author: ParthaI

config/github.spc

@@ -6,6 +6,8 @@ connection "github" {
   #   https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token for more information.
   # - GitHub application installation access token, e.g., `ghs_UdmjfiKzVbFJNBsaiePwFPCmKeFakeToken`
   #   https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app for more information.
+  # - Fine-grained personal access token, e.g., `github_pat_11AKSHEQA0VptbjTZnO4at_lgZnoGwpuXb1noakeOG337zfnDQYIB5iJSUkUlMt8nH6KPO3NFakeToken`
+  #   https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token for more information.
   # Can also be set with the GITHUB_TOKEN environment variable.
   # token = "ghp_3b99b12218f63bcd702ad90d345975ef6c62f7d8"
 

docs/index.md

@@ -61,8 +61,8 @@ steampipe plugin install github
 
 | Item        | Description|
 |-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Credentials | The GitHub plugin uses a personal access token to authenticate to the GitHub APIs.
-| Permissions | You must create a [personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) and assign the following scopes:<br />&nbsp;&nbsp;&nbsp;&nbsp;- `repo` (all)<br />&nbsp;&nbsp;&nbsp;&nbsp;- `read:org`<br />&nbsp;&nbsp;&nbsp;&nbsp;- `gist`<br />&nbsp;&nbsp;&nbsp;&nbsp;- `read:user`<br />&nbsp;&nbsp;&nbsp;&nbsp;- `user:email`
+| Credentials | The GitHub plugin supports personal access tokens, fine-grained personal access tokens, and GitHub App installation tokens to authenticate with the GitHub APIs.
+| Permissions | You can authenticate using one of the following token types:<br />&nbsp;&nbsp;&nbsp;&nbsp;- [Personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) and assign the following scopes:<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- `repo` (all)<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- `read:org`<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- `gist`<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- `read:user`<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- `user:email`<br />&nbsp;&nbsp;&nbsp;&nbsp;- [GitHub App installation token](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user#identifying-and-authorizing-users-for-github-apps)<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- [Permissions required for GitHub Apps](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28)<br />&nbsp;&nbsp;&nbsp;&nbsp;- [Fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)<br /> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- Each table's documentation outlines the permissions needed to query it.
 | Radius      | The GitHub plugin query scope is generally the same as the GitHub API. Usually, this means you can list private resources that you have access to, as well as public resources that you own, or that are owned by organizations to which you belong. The same GitHub APIs are used to get information for public resources, but the public items are returned in list calls (because there would be too many). This has an interesting side effect in Steampipe in that you can sometimes query _a specific item_ by _a specific key column or columns_ that does not show up in a list query.<br /><br />For example, `select * from github_my_organization` will list details about all the GitHub Organizations to which you belong. `select * from github_organization where login = 'postgres'` will show you the publicly available details about the `postgres` organization, which didn't show up in your first query! It works this way in Steampipe because [that's how it works in the API](https://docs.github.com/en/rest/reference/orgs#list-organizations-for-a-user). While this may seem counter-intuitive at first, it actually can be quite useful. |
 | Resolution  | 1. Credentials in the Steampipe configuration file (`~/.steampipe/config/github.spc`) <br />2. Credentials specified in environment variables, e.g., `GITHUB_TOKEN`.
 
@@ -79,6 +79,8 @@ connection "github" {
   #   https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token for more information.
   # - GitHub application installation access token, e.g., `ghs_UdmjfiKzVbFJNBsaiePwFPCmKeFakeToken`
   #   https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app for more information.
+  # - Fine-grained personal access token, e.g., `github_pat_11AKSHEQA0VptbjTZnO4at_lgZnoGwpuXb1noakeOG337zfnDQYIB5iJSUkUlMt8nH6KPO3NFakeToken`
+  #   https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token for more information.
   # Can also be set with the GITHUB_TOKEN environment variable.
   # token = "ghp_3b99b12218f63bcd702ad90d345975ef6c62f7d8"
 
@@ -102,7 +104,7 @@ connection "github" {
 }
 ```
 
-- `token` - [Personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) for your GitHub account or a [Github App installation access token](https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app).
+- `token` - [Personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) for your GitHub account or a [Github App installation access token](https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app) or a [Fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).
  This can also be set via the `GITHUB_TOKEN` environment variable.
 - `base_url` - GitHub Enterprise users have a custom URL location (e.g. `https://github.example.com`). Not required for GitHub cloud. This can also be via the `GITHUB_BASE_URL` environment variable.
 - `app_id` - [Github App ID](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation) for your Github organization. This can also be set via the `GITHUB_APP_ID` environment variable.

docs/tables/github_actions_artifact.md

@@ -12,6 +12,11 @@ GitHub Actions Artifacts are the files created when you build and test your code
 
 The `github_actions_artifact` table provides insights into artifacts generated by GitHub Actions workflows. As a software developer or DevOps engineer, explore artifact-specific details through this table, including metadata and download URLs. Utilize it to uncover information about artifacts, such as their size, download location, and associated workflow runs.
 
+To query this table using a [fine-grained access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token), the following permissions are required:
+  - Repository permissions:
+    - Actions (Read-only): Required to access all columns.
+    - Metadata (Read-only): Required to access general repository metadata.
+
 **Important Notes**
 - You must specify the `repository_full_name` column in `where` or `join` clause to query the table. 
 

docs/tables/github_actions_repository_runner.md

@@ -12,6 +12,11 @@ GitHub Actions is a CI/CD service provided by GitHub which allows automating sof
 
 The `github_actions_repository_runner` table provides insights into the self-hosted runners of GitHub Actions for a specific repository. As a DevOps engineer, you can explore runner-specific details through this table, including runner IDs, names, operating systems, statuses, and associated metadata. Utilize it to manage and monitor your self-hosted runners, ensuring they are functioning properly and are up-to-date.
 
+To query this table using a [fine-grained access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token), the following permissions are required:
+  - Organization permissions:
+    - Metadata (Read-only): Required to access general repository metadata.
+    - Self-hosted runners (Read-only): Required to access all columns.
+
 **Important Notes**
 - You must specify the `repository_full_name` column in `where` or `join` clause to query the table.
 

docs/tables/github_actions_repository_secret.md

@@ -12,6 +12,11 @@ GitHub Actions is a service provided by GitHub that allows you to automate, cust
 
 The `github_actions_repository_secret` table provides insights into secrets stored within a GitHub repository. As a security engineer, explore secret-specific details through this table, including the names of secrets and the dates they were created or updated. Utilize it to uncover information about secrets, such as those that may be outdated or unused, providing a comprehensive view of the repository's security measures.
 
+To query this table using a [fine-grained access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token), the following permissions are required:
+  - Repository permissions:
+    - Metadata (Read-only): Required to access general repository metadata.
+    - Secrets (Read-only): Required to access all columns.
+
 **Important Notes**
 - You must specify the `repository_full_name` column in `where` or `join` clause to query the table.
 

docs/tables/github_actions_repository_workflow_run.md

@@ -12,6 +12,11 @@ GitHub Actions is a CI/CD solution that allows you to automate how you build, te
 
 The `github_actions_repository_workflow_run` table provides insights into GitHub Actions Repository Workflow Runs. As a software developer or DevOps engineer, explore details of each workflow run in a repository through this table, including its status, conclusion, and other metadata. Utilize it to monitor and analyze the performance and results of your CI/CD workflows, ensuring your software development process is efficient and effective.
 
+To query this table using a [fine-grained access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token), the following permissions are required:
+  - Repository permissions:
+    - Actions (Read-only): Required to access all columns.
+    - Metadata (Read-only): Required to access general repository metadata.
+
 **Important Notes**
 - You must specify the `repository_full_name` column in `where` or `join` clause to query the table. 
 

docs/tables/github_audit_log.md

@@ -12,6 +12,8 @@ GitHub Audit Logs is a feature within GitHub that allows you to keep track of wh
 
 The `github_audit_log` table provides insights into user activity within GitHub. As a Security Analyst, explore user-specific actions through this table, including performed actions, involved repositories, and action timestamps. Utilize it to uncover information about user actions, such as repository changes, team membership alterations, and other potential security risks.
 
+If using a [fine-grained access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token), no permissions are required.
+
 **Important Notes**
 - You must specify the `organization` column in `where` or `join` clause to query the table.
 - This table only works for organizations on an [GitHub Enterprise plan](https://docs.github.com/en/enterprise-cloud@latest/admin/overview/about-enterprise-accounts).

docs/tables/github_blob.md

@@ -12,6 +12,11 @@ GitHub Repositories are a fundamental resource in GitHub. They allow users to ho
 
 The `github_blob` table provides the contents of files within GitHub Repositories. As a developer or project manager, explore each repository's contents. Utilize it to uncover information about specific files in the repository, such as configuration files.
 
+To query this table using a [fine-grained access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token), the following permissions are required:
+  - Repository permissions:
+    - Contents (Read-only): Required to access all columns.
+    - Metadata (Read-only): Required to access general repository metadata.
+
 **Important Notes**
 - You must specify the `repository_full_name` and `blob_sha` columns in `where` or `join` clause to query the table.
 

docs/tables/github_branch.md

@@ -12,6 +12,11 @@ GitHub Branches are references within a repository that point to the state of a
 
 The `github_branch` table provides insights into branches within GitHub repositories. As a developer or project manager, explore branch-specific details through this table, including name, commit, protected status, and associated metadata. Utilize it to uncover information about branches, such as those with protected status, the commit associated with each branch, and the verification of branch protections.
 
+To query this table using a [fine-grained access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token), the following permissions are required:
+  - Repository permissions:
+    - Contents (Read-only): Required to access all columns.
+    - Metadata (Read-only): Required to access general repository metadata.
+
 **Important Notes**
 - You must specify the `repository_full_name` column in `where` or `join` clause to query the table.
 

docs/tables/github_branch_protection.md

@@ -12,6 +12,12 @@ GitHub Branch Protection is a feature within GitHub that allows you to define ce
 
 The `github_branch_protection` table provides insights into branch protection rules within GitHub. As a DevOps engineer or a repository manager, explore branch-specific details through this table, including the enforcement of status checks, pull request reviews, and push restrictions. Utilize it to uncover information about branch protections, such as those with strict requirements, the enforcement of signed commits, and the restrictions on who can push to the branch.
 
+To query this table using a [fine-grained access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token), the following permissions are required:
+  - Repository permissions:
+    - Administration (Read-only): Required to access general branch protection details.
+    - Contents (Read-only): Required to access the `matching_branches` column.
+    - Metadata (Read-only): Required to access general repository metadata.
+
 **Important Notes**
 - You must specify the `repository_full_name` column in `where` or `join` clause to query the table.