-
Notifications
You must be signed in to change notification settings - Fork 63
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* readme update --------- Co-authored-by: Roy Blit <[email protected]> Co-authored-by: liavc <[email protected]>
- Loading branch information
3 people
authored
Nov 29, 2023
1 parent
5f43540
commit a4e2278
Showing
1 changed file
with
83 additions
and
29 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,8 @@ | ||
| <div align="center"> | ||
| <a href="https://www.legitsecurity.com"> | ||
| <img width="100" alt="Legitify Logo" src="https://github.com/Legit-Labs/legitify/assets/74864790/c76dc765-e8fd-498e-ab92-1228eb5a1f2d"> | ||
| </a> | ||
| </div> | ||
| <div align="center"> | ||
|
|
||
| [](https://github.com/Legit-Labs/legitify/actions/workflows/build_and_test.yaml) | ||
|
|
@@ -13,6 +18,13 @@ | |
| Strengthen the security posture of your source-code management! <br/> | ||
| Detect and remediate misconfigurations, security and compliance issues across all your GitHub and GitLab assets with ease 🔥 <br/> | ||
| by [Legit Security](https://www.legitsecurity.com/). | ||
|
|
||
| <b> | ||
| Wonder what Legit Security does? | ||
| </b> | ||
|
|
||
| We do ASPM and software supply chain security, for more information check out the [comparison table](#legitify-vs-the-legit-security-platform) | ||
|
|
||
| </div> | ||
|
|
||
| https://user-images.githubusercontent.com/107790206/210602039-2d022692-87ea-4005-b9c6-f091158de3ce.mov | ||
|
|
@@ -22,6 +34,7 @@ https://user-images.githubusercontent.com/107790206/210602039-2d022692-87ea-4005 | |
| Installation is possible in several ways: | ||
|
|
||
| - For macOS (or linux) using homebrew: | ||
|
|
||
| ``` | ||
| brew install legitify | ||
| ``` | ||
|
|
@@ -39,6 +52,7 @@ go run main.go analyze ... | |
| ``` | ||
|
|
||
| - As a GitHub CLI extension (check out https://github.com/Legit-Labs/gh-legitify for more information) | ||
|
|
||
| ``` | ||
| gh extension install legit-labs/gh-legitify | ||
| gh legitify | ||
|
|
@@ -84,7 +98,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 | ||
| ``` | ||
|
|
||
|
|
||
| ## Commands | ||
|
|
||
| ### analyze | ||
|
|
@@ -96,12 +109,12 @@ SCM_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 GitHub organizations or GitLab group | ||
| - `--repo`: will limit the analysis to the specified GitHub repositories or GitLab projects | ||
| - `--scm`: specify the source code management platform. Possible values are: `github` or `gitlab`. Defaults to `github`. Please note: when running on GitLab, `--scm gitlab` is required. | ||
| - `--enterprise`: will specify which enterprises should be analyzed. Please note: in order to analyze an enterprise, an enterprise slug must be provided. | ||
|
|
||
| - `--enterprise`: will specify which enterprises should be analyzed. Please note: in order to analyze an enterprise, an enterprise slug must be provided. | ||
|
|
||
| ``` | ||
| SCM_TOKEN=<your_token> legitify analyze --org org1,org2 --namespace organization,member | ||
|
|
@@ -120,69 +133,75 @@ GPT-3 based analysis of the security posture of the provided repository or organ | |
| **NOTE: The repository/organization metadata is sent to openai servers.** | ||
|
|
||
| Flags: | ||
|
|
||
| - `--org`: will limit the analysis to the specified GitHub organizations or GitLab group | ||
| - `--repo`: will limit the analysis to the specified GitHub repositories or GitLab projects | ||
| - `--scm`: specify the source code management platform. Possible values are: `github` or `gitlab`. Defaults to `github`. | ||
| - `--token`: token for the SCM (or set the SCM_TOKEN environment variable) | ||
| - `--openai-token`: token for openai API (or set OPENAI_TOKEN environment variable) | ||
| - `--openai-token`: token for openai API (or set OPENAI_TOKEN environment variable) | ||
|
|
||
| Must provide either `--org` or `--repo` or both. | ||
|
|
||
| Generating openai token: | ||
|
|
||
| 1. Go to https://beta.openai.com/signup and create an openai account | ||
| 2. Under https://platform.openai.com/account/api-keys press "Create new secret key" | ||
|
|
||
| ## GitHub Action Usage | ||
|
|
||
| You can also run legitify as a GitHub action in your workflows, see the **action_examples** directory for concrete examples. | ||
|
|
||
|
|
||
| ## Requirements | ||
|
|
||
| ### GitHub (Cloud and Enterprise Server) | ||
|
|
||
| 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 (`SCM_TOKEN`). | ||
| 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/). | ||
| Fine-grained personal access tokens are currently not supported. | ||
|
|
||
| ### GitHub Enterprise Server | ||
| You can run legitify against a GitHub Enterprise Server instance if you set the endpoint URL in the environment variable ``SERVER_URL``: | ||
|
|
||
| You can run legitify against a GitHub Enterprise Server instance if you set the endpoint URL in the environment variable `SERVER_URL`: | ||
|
|
||
| ```sh | ||
| export SERVER_URL="https://github.example.com/" | ||
| SCM_TOKEN=<your_token> legitify analyze --org org1,org2 --namespace organization,member | ||
| ``` | ||
|
|
||
| ### GitLab Cloud/Server | ||
|
|
||
| 1. As mentioned in the previous section, you need to be an owner of at least one GitLab group. Otherwise, you can still use the tool if you're an admin of at least one project inside a group, in which case you'll be able to see only project-related policies results. | ||
| 2. legitify requires a GitLab personal access token (PAT) to analyze your resources successfully, which can be either provided as an argument (`-t`) or as an environment variable (`SCM_TOKEN`). | ||
| The PAT needs the following scopes for full analysis: | ||
| ``` | ||
| read_api, read_user, read_repository, read_registry | ||
| ``` | ||
| See [Creating a Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) for more information. | ||
| To run legitify against GitLab Cloud set the scm flag to gitlab `--scm gitlab`, to run against GitLab Server you need to provide also a SERVER_URL: | ||
| The PAT needs the following scopes for full analysis: | ||
| ` read_api, read_user, read_repository, read_registry` | ||
| See [Creating a Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) for more information. | ||
| To run legitify against GitLab Cloud set the scm flag to gitlab `--scm gitlab`, to run against GitLab Server you need to provide also a SERVER_URL: | ||
|
|
||
| ```sh | ||
| export SERVER_URL="https://gitlab.example.com/" | ||
| SCM_TOKEN=<your_token> legitify analyze --namespace organization --scm gitlab | ||
| ``` | ||
| > **_NOTE 1:_** To ignore invalid server certificate, please pass the `ignore-invalid-certificate` flag | ||
|
|
||
| > **_NOTE 2:_** For non-premium GitLab accounts some policies (such as branch protection policies) will be skipped | ||
| > **_NOTE 1:_** To ignore invalid server certificate, please pass the `ignore-invalid-certificate` flag | ||
| > **_NOTE 2:_** For non-premium GitLab accounts some policies (such as branch protection policies) will be skipped | ||
| ## Namespaces | ||
|
|
||
| Namespaces in legitify are resources that are collected and run against the policies. | ||
| Currently, the following namespaces are supported: | ||
|
|
||
| 1. `organization` - GitHub organization (or GitLab group) 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` - contributor level policies (e.g., "Stale Admin Found") | ||
| 4. `repository` - GitHub repository (or GitLab Project) 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` - contributor level policies (e.g., "Stale Admin Found") | ||
| 4. `repository` - GitHub repository (or GitLab Project) 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. | ||
|
|
@@ -228,13 +247,12 @@ When outputting in a human-readable format, legitify support the conventional `- | |
|
|
||
| - Use the `--failed-only` flag to filter-out passed/skipped checks from the result. | ||
| - Use the `--ignore-policies-path $PATH` and provide a file with the policies you want to ignore to skip specific policies. | ||
| One policy per line, e.g. | ||
| ``` | ||
| no_conversation_resolution | ||
| requires_status_checks ─╯ | ||
| ``` | ||
| One policy per line, e.g. | ||
| `no_conversation_resolution | ||
| requires_status_checks ─╯` | ||
|
|
||
| ## Scorecard Support - Only for GitHub server/cloud repositories | ||
|
|
||
| [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. | ||
|
|
@@ -266,12 +284,11 @@ legitify runs the following scorecard checks: | |
| |Webhooks|V|V| | ||
|
|
||
| ## Policies | ||
|
|
||
| legitify comes with a set of policies for each SCM in the `policies/` directory. | ||
|
|
||
| These policies are documented [here](https://legitify.dev). | ||
|
|
||
| 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. | ||
|
|
@@ -281,3 +298,40 @@ Here are some resources to help you get started: | |
| - [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) | ||
| - [Open a Pull Request](https://github.com/Legit-Labs/legitify/compare) | ||
|
|
||
| ## Support | ||
|
|
||
| If you have questions about legitify or need any assistance with its operation, don't hesitate to [reach out](mailto:[email protected]). Our team is committed to providing support and ensuring a smooth experience. | ||
|
|
||
| ## Legitify vs. the Legit Security platform | ||
|
|
||
| If you liked Legitify, you are going to love the Legit Security Platform! | ||
|
|
||
| - It automates Legitify checks for the entire environments, discovers more systems and shows all results in a simple web app to manage at scale. | ||
| - Legit security is a complete CI/CD security solution together with Application Security Posture Management (ASPM) that covers application security end-to-end. | ||
| - It is a SaaS platform, built for engineering, DevOps and security teams and trusted by many leading organizaitons around the world. | ||
|
|
||
| Below is a comfeature parison between Legitify and Legit: | ||
|
|
||
| | **Capability** | **Legitify** | **Legit Security Platform** | | ||
| | --------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------ | | ||
| | Supported Platforms | GitHub cloud & server <br> Gitlab cloud & server | ALL Major SCMs (incl. Azure DevOps, Bitbucket and more)<br> CI/CD systems (e.g. Jenkins) <br> Package Registries (e.g. JFrog Artifactory | | ||
| | Risk detection | SCM's Misconfigurations only | SCM's Misconfigurations <br> CI Misconfigurations <br> CD Misconfigurations <br> Package Registries Misconfigurations <br> Pipeline risks <br> Secrets <br> IaC <br> Security Incidents <br> And more...| | ||
| | SDLC asset management | - | Yes | | ||
| | Compliance Report | [OSSF SCM Best Practices](https://best.openssf.org/SCM-BestPractices/) | SSDF <br> SLSA <br> SOC2 <br> ISO 27001 <br> FedRAMP <br> and more...| | ||
| | Issue & Policy Management | - | Yes | | ||
| | Contextualized Information | No Context | Prioritize issues with contextualized information through Legit's Code To Cloud technology | | ||
| | Custom policies | - | Yes | | ||
| | Policy drifts detection | - | Yes | | ||
| | Workspaces & product groups | - | Yes | | ||
| | Ticketing & Alerting | - | Jira, Slack, etc. | | ||
| | Ingest risk | - | Import APIs and integrations with SAST, SCA and other testing solutions | | ||
| | Rest APIs | -| Yes | | ||
|
|
||
| To check out Legit, visit our [website](https://www.legitsecurity.com/) or directly [book a demo](https://info.legitsecurity.com/book-a-demo) | ||
|
|
||
| <div align="center"> | ||
| <a href="https://www.legitsecurity.com"> | ||
| <img width="250" alt="Legitify Logo" src="https://github.com/Legit-Labs/legitify/assets/74864790/c76dc765-e8fd-498e-ab92-1228eb5a1f2d"> | ||
| </a> | ||
| </div> | ||