feat: introduce legitify github action (#93)

add legitify github action

README.md

@@ -6,7 +6,6 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/Legit-Labs/legitify)](https://goreportcard.com/report/github.com/Legit-Labs/legitify)
 [![Maintained By Legit Security](https://img.shields.io/badge/Maintained%20by-Legit%20Security-blueviolet)](https://www.legitsecurity.com/)
 
-
  <img width="250" alt="Legitify Logo" src="https://user-images.githubusercontent.com/74864790/174815311-746a0c98-9a1f-44a9-808c-035788edfd4d.png">
 
 Strengthen the security posture of your GitHub organization! <br/>
@@ -17,59 +16,79 @@ Detect and remediate misconfigurations, security and compliance issues across al
 https://user-images.githubusercontent.com/74864790/178964716-825840a6-d714-4b1d-a41e-efa2728507a6.mp4
 
 ## Installation
+
 1. You can download the latest legitify release from https://github.com/Legit-Labs/legitify/releases, each archive contains:
-  * Legitify binary for the desired platform
-  * Built-in policies provided by Legit Security
+
+- Legitify binary for the desired platform
+- Built-in policies provided by Legit Security
+
 2. From source with the following steps:
+
 ```
 git clone git@github.com:Legit-Labs/legitify.git
 go run main.go analyze ...
 ```
 
 ## Provenance
+
 To enhance the software supply chain security of legitify's users, as of v0.1.6, every legitify release contains a [SLSA Level 3 Provenance](https://github.com/slsa-framework/slsa-github-generator/blob/main/internal/builders/generic/README.md) document.  
 The provenance document refers to all artifacts in the release, as well as the generated docker image.  
 You can use [SLSA framework's official verifier](https://github.com/slsa-framework/slsa-verifier) to verify the provenance.  
 Example of usage for the darwin_arm64 architecture for the v0.1.6 release:
+
 ```
 VERSION=0.1.6
 ARCH=darwin_arm64
 ./slsa-verifier verify-artifact --source-branch main --builder-id 'https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v1.2.2' --source-uri "git+https://github.com/Legit-Labs/legitify" --provenance-path multiple.intoto.jsonl ./legitify_${VERSION}_${ARCH}.tar.gz
 ```
 
 ## Requirements
+
 1. To get the most out of legitify, you need to be an owner of at least one GitHub organization. Otherwise, you can still use the tool if you're an admin of at least one repository inside an organization, in which case you'll be able to see only repository-related policies results.
 2. legitify requires a GitHub personal access token (PAT) to analyze your resources successfully, which can be either provided as an argument (`-t`) or as an environment variable (`$GITHUB_ENV`).
    The PAT needs the following scopes for full analysis:
-  ```
-  admin:org, read:enterprise, admin:org_hook, read:org, repo, read:repo_hook
-  ```
+
+```
+admin:org, read:enterprise, admin:org_hook, read:org, repo, read:repo_hook
+```
+
 See [Creating a Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) for more information.  
 Fine-grained personal access tokens are currently not supported because they do not support GitHub's GraphQL (https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/)
 
-## Usage
+## CLI Usage
+
 ```
 LEGITIFY_TOKEN=<your_token> legitify analyze
 ```
+
 By default, legitify will check the policies against all your resources (organizations, repositories, members, actions).
 
 You can control which resources will be analyzed with command-line flags namespace and org:
-- `--namespace (-n)`: will analyze policies that relate to the specified resources 
+
+- `--namespace (-n)`: will analyze policies that relate to the specified resources
 - `--org`: will limit the analysis to the specified organizations
 
 ```
 LEGITIFY_TOKEN=<your_token> legitify analyze --org org1,org2 --namespace organization,member
 ```
+
 The above command will test organization and member policies against org1 and org2.
 
+## GitHub Action Usage
+
+You can also run legitify as a GitHub action in your workflows, see the **action_examples** directory for concrete examples.
+
 ## GitHub Enterprise Support
-You can run legitify against a GitHub Enterprise instance if you set the endpoint URL in the environment variable ``SERVER_URL``:
+
+You can run legitify against a GitHub Enterprise instance if you set the endpoint URL in the environment variable `SERVER_URL`:
 
 ```sh
 export SERVER_URL="https://github.example.com/"
 LEGITIFY_TOKEN=<your_token> legitify analyze --org org1,org2 --namespace organization,member
 ```
+
 ## GitLab Cloud/Server Support
+
 To run legitify against GitLab Cloud set the scm flag to gitlab `--scm gitlab`, to run against GitLab Server you need to provide also SERVER_URL:
 
 ```sh
@@ -78,55 +97,69 @@ LEGITIFY_TOKEN=<your_token> legitify analyze --namespace organization --scm gitl
 ```
 
 ## Namespaces
+
 Namespaces in legitify are resources that are collected and run against the policies.
 Currently, the following namespaces are supported:
+
 1. `organization` - organization level policies (e.g., "Two-Factor Authentication Is Not Enforced for the Organization")
-2. `actions`      - organization GitHub Actions policies (e.g., "GitHub Actions Runs Are Not Limited To Verified Actions")
-3. `member`       - organization members policies (e.g., "Stale Admin Found")
-4. `repository`   - repository level policies (e.g., "Code Review By At Least Two Reviewers Is Not Enforced")
+2. `actions` - organization GitHub Actions policies (e.g., "GitHub Actions Runs Are Not Limited To Verified Actions")
+3. `member` - organization members policies (e.g., "Stale Admin Found")
+4. `repository` - repository level policies (e.g., "Code Review By At Least Two Reviewers Is Not Enforced")
 5. `runner_group` - runner group policies (e.g, "runner can be used by public repositories")
 
 By default, legitify will analyze all namespaces. You can limit only to selected ones with the `--namespace` flag, and then a comma separated list of the selected namespaces.
 
 ## Output Options
+
 By default, legitify will output the results in a human-readable format.
 This includes the list of policy violations listed by severity,
 as well as a summary table that is sorted by namespace.
 
 ### Output Formats
+
 Using the `--output-format (-f)` flag, legitify supports outputting the results in the following formats:
+
 1. `human-readable` - Human-readable text (default).
 2. `json` - Standard JSON.
 
 ### Output Schemes
-Using the `--output-scheme` flag, legitify supports outputting the results in different grouping schemes. 
+
+Using the `--output-scheme` flag, legitify supports outputting the results in different grouping schemes.
 Note: `--output-format=json` must be specified to output non-default schemes.
+
 1. `flattened` - No grouping; A flat listing of the policies, each with its violations (default).
 2. `group-by-namespace` - Group the policies by their namespace.
 3. `group-by-resource` - Group the policies by their resource e.g. specific organization/repository.
 4. `group-by-severity` - Group the policies by their severity.
 
 ### Output Destinations
+
 - `--output-file` - full path of the output file (default: no output file, prints to stdout).
 - `--error-file` - full path of the error logs (default: ./error.log).
 
 ### Coloring
+
 When outputting in a human-readable format, legitify support the conventional `--color[=when]` flag, which has the following options:
+
 - `auto` - colored output if stdout is a terminal, uncolored otherwise (default).
 - `always` - colored output regardless of the output destination.
 - `none` - uncolored output regardless of the output destination.
 
 ### Misc
+
 - Use the `--failed-only` flag to filter-out passed/skipped checks from the result.
 
 ## Scorecard Support
+
 [scorecard](https://github.com/ossf/scorecard) is an OSSF's open-source project:
+
 > Scorecards is an automated tool that assesses a number of important heuristics ("checks") associated with software security and assigns each check a score of 0-10. You can use these scores to understand specific areas to improve in order to strengthen the security posture of your project. You can also assess the risks that dependencies introduce, and make informed decisions about accepting these risks, evaluating alternative solutions, or working with the maintainers to make improvements.
 
 legitify supports running scorecard for all of the organization's repositories, enforcing score policies and showing the results using the `--scorecard` flag:
+
 - `no` - do not run scorecard (default).
 - `yes` - run scorecard and employ a policy that alerts on each repo score below 7.0.
-- `verbose` - run scorecard, employ a policy that alerts on each repo score below 7.0, and embed its output to legitify's output. 
+- `verbose` - run scorecard, employ a policy that alerts on each repo score below 7.0, and embed its output to legitify's output.
 
 legitify runs the following scorecard checks:
 |Check|Public Repository|Private Repository|
@@ -149,14 +182,17 @@ legitify runs the following scorecard checks:
 |Webhooks|V|V|
 
 ## Policies
+
 legitify comes with a set of policies in the `policies/github` directory.
 These policies are documented [here](https://legitify.dev/policies.html).
 
 In addition, you can use the `--policies-path (-p)` flag to specify a custom directory for OPA policies.
 
 ## Contribution
+
 Thank you for considering contributing to Legitify! We encourage and appreciate any kind of contribution.
 Here are some resources to help you get started:
+
 - [Contribution Guide](https://github.com/Legit-Labs/legitify/blob/main/CONTRIBUTING.md)
 - [Code of Conduct](https://github.com/Legit-Labs/legitify/blob/main/CODE_OF_CONDUCT.md)
 - [Open an Issue](https://github.com/Legit-Labs/legitify/issues/new/choose)

action.yml

@@ -0,0 +1,20 @@
+name: "Legitify Analyze"
+description: "Legitify GitHub Action"
+inputs:
+  github_token:
+    description: "GitHub Personal Access Token"
+    required: true
+  analyze_self_only:
+    description: "If this is set, only the repo where this action is called from will be analyzed"
+    required: false
+    default: "false"
+  repositories:
+    description: "Strings of owner/repo. If this is set, only selected repositories will be analyzed"
+    required: false
+  legitify_base_version:
+    description: "The base version of legitify to use. Non breaking changes will be auto updated."
+    required: false
+    default: "0.1"
+runs:
+  using: "node16"
+  main: "index.js"

action_examples/analyze_repos.yml

@@ -0,0 +1,19 @@
+# Analyze two specific repositories: 'owner1/repo1' and 'owner1/repo2'
+name: Legitify Analyze
+on:
+  workflow_dispatch:
+  schedule:
+    # Runs "At 11:00 on every day-of-week from Monday through Friday"
+    - cron: "0 11 * * 1-5"
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Legitify Action
+        uses: Legit-Labs/legitify@main # it is recommended to use a specific commit hash
+        with:
+          github_token: ${{ secrets.PAT_FOR_LEGITIFY }}
+          repositories: owner1/repo1 owner1/repo2

action_examples/analyze_self_org.yml

@@ -0,0 +1,18 @@
+# This is the default behavior, will analyze the organization from which the action is running from.
+name: Legitify Analyze
+on:
+  workflow_dispatch:
+  schedule:
+    # Runs "At 11:00 on every day-of-week from Monday through Friday"
+    - cron: "0 11 * * 1-5"
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Legitify Action
+        uses: Legit-Labs/legitify@main # it is recommended to use a specific commit hash
+        with:
+          github_token: ${{ secrets.PAT_FOR_LEGITIFY }}

action_examples/analyze_self_repo.yml

@@ -0,0 +1,19 @@
+# Analyze the repo from which the action is running from.
+name: Legitify Analyze
+on:
+  workflow_dispatch:
+  schedule:
+    # Runs "At 11:00 on every day-of-week from Monday through Friday"
+    - cron: "0 11 * * 1-5"
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Legitify Action
+        uses: Legit-Labs/legitify@main # it is recommended to use a specific commit hash
+        with:
+          github_token: ${{ secrets.PAT_FOR_LEGITIFY }}
+          analyze_self_only: "true"

action_examples/analyze_using_specific_version.yml

@@ -0,0 +1,21 @@
+# This workflow will run legitify analyze using a specific version of legitify.
+# In this example, 0.1.6. For all versions, see https://github.com/Legit-Labs/legitify/releases
+name: Legitify Analyze
+on:
+  workflow_dispatch:
+  schedule:
+    # Runs "At 11:00 on every day-of-week from Monday through Friday"
+    - cron: "0 11 * * 1-5"
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Legitify Action
+        uses: Legit-Labs/legitify@main # it is recommended to use a specific commit hash
+        with:
+          github_token: ${{ secrets.PAT_FOR_LEGITIFY }}
+          legitify_version: "0.1.6"
+          analyze_self_only: "true"