-
Notifications
You must be signed in to change notification settings - Fork 30
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #33 from aquasecurity/update-docs
chore(docs): Update docs
- Loading branch information
Showing
7 changed files
with
292 additions
and
7 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 |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| # Architecture | ||
|
|
||
| This document aims to answer the question *Where is the code that does X?* | ||
|
|
||
| ## Project Layout | ||
|
|
||
| The directory structure is broken down as follows: | ||
|
|
||
| - `cmd/` - These CLI tools are primarily used during development for end-to-end testing without needing to pull the library into trivy/tfsec etc. | ||
| - `rules` - All of the rules and policies are defined in this directory. | ||
| - `pkg/spec` - Logic to handle standardized specs such as CIS. | ||
| - `pkg/rules` - This package exposes internal rules, and imports them accordingly (see _rules.go_). | ||
| - `test` - Integration tests and other high-level tests that require a full build of the project. | ||
| - `scripts` - Usefule generation scripts for bundle generation and verification purposes. |
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 |
|---|---|---|
| @@ -0,0 +1,95 @@ | ||
| # Contributing | ||
|
|
||
| Welcome, and thank you for considering contributing to trivy-policies! | ||
|
|
||
| The following guide gives an overview of the project and some directions on how to make common types of contribution. If something is missing, or you get stuck, please [start a discussion](https://github.com/aquasecurity/trivy/discussions/new) and we'll do our best to help. | ||
|
|
||
| ### Writing Rules | ||
|
|
||
| Writing a new rule can be relatively simple, but there are a few things to keep in mind. The following guide will help you get started. | ||
|
|
||
| First of all, you should check if the provider your rule targets is supported by _defsec_. If it's not, you'll need to add support for it. See [Adding Support for a New Cloud Provider](https://github.com/aquasecurity/defsec/blob/master/CONTRIBUTING.md#adding-support-for-a-new-cloud-provider) for more information. You can check if support exists by looking for a directory with the provider name in `pkg/providers`. If you find your provider, navigate into the directory and check for a directory with the name of the service you're targeting. If you can't find that, you'll need to add support for it. See [Adding Support for a New Service](https://github.com/aquasecurity/defsec/blob/master/CONTRIBUTING.md#adding-support-for-a-new-service) for more information. | ||
|
|
||
| Next up, you'll need to check if the properties you want to target are supported, and if not, add support for them. The guide on [Adding Support for a New Service](https://github.com/aquasecurity/defsec/blob/master/CONTRIBUTING.md#adding-support-for-a-new-service) covers adding new properties. | ||
|
|
||
| At last, it's time to write your rule code! Rules are defined using _OPA Rego_. You can find a number of examples in the `rules/cloud/policies` directory. The [OPA documentation](https://www.openpolicyagent.org/docs/latest/policy-language/) is a great place to start learning Rego. You can also check out the [Rego Playground](https://play.openpolicyagent.org/) to experiment with Rego, and [join the OPA Slack](https://slack.openpolicyagent.org/). | ||
|
|
||
| Create a new file in `rules/cloud/policies` with the name of your rule. You should nest it in the existing directory structure as applicable. The package name should be in the format `builtin.PROVIDER.SERVICE.ID`, e.g. `builtin.aws.rds.aws0176`. | ||
|
|
||
| Running `make id` will provide you with the next available _ID_ for your rule. You can use this ID in your rule code to identify it. | ||
|
|
||
| A simple rule looks like the following example: | ||
|
|
||
| ```rego | ||
| # METADATA | ||
| # title: "RDS IAM Database Authentication Disabled" | ||
| # description: "Ensure IAM Database Authentication is enabled for RDS database instances to manage database access" | ||
| # scope: package | ||
| # schemas: | ||
| # - input: schema["aws"] | ||
| # related_resources: | ||
| # - https://docs.aws.amazon.com/neptune/latest/userguide/iam-auth.html | ||
| # custom: | ||
| # avd_id: AVD-AWS-0176 | ||
| # provider: aws | ||
| # service: rds | ||
| # severity: MEDIUM | ||
| # short_code: enable-iam-auth | ||
| # recommended_action: "Modify the PostgreSQL and MySQL type RDS instances to enable IAM database authentication." | ||
| # input: | ||
| # selector: | ||
| # - type: cloud | ||
| # subtypes: | ||
| # - service: rds | ||
| # provider: aws | ||
| package builtin.aws.rds.aws0176 | ||
| deny[res] { | ||
| instance := input.aws.rds.instances[_] | ||
| instance.engine.value == ["postgres", "mysql"][_] | ||
| not instance.iamauthenabled.value | ||
| res := result.new("Instance does not have IAM Authentication enabled", instance.iamauthenabled) | ||
| } | ||
| ``` | ||
|
|
||
| In fact, this is the code for an actual rule. You can find it in `rules/cloud/policies/aws/rds/enable_iam_auth.rego`. | ||
|
|
||
| The metadata is the top section that starts with `# METADATA`, and is fairly verbose. You can copy and paste from another rule as a starting point. This format is effectively _yaml_ within a Rego comment, and is [defined as part of Rego itself](https://www.openpolicyagent.org/docs/latest/policy-language/#metadata). | ||
|
|
||
| Let's break the metadata down. | ||
|
|
||
| - `title` is fairly self-explanatory - it is a title for the rule. The title should clearly and succinctly state the problem which is being detected. | ||
| - `description` is also fairly self-explanatory - it is a description of the problem which is being detected. The description should be a little more verbose than the title, and should describe what the rule is trying to achieve. Imagine it completing a sentence starting with `You should...`. | ||
| - `scope` is used to define the scope of the policy. In this case, we are defining a policy that applies to the entire package. _defsec_ only supports using package scope for metadata at the moment, so this should always be the same. | ||
| - `schemas` tells Rego that it should use the `AWS` schema to validate the use of the input data in the policy. We currently support [these](https://github.com/aquasecurity/trivy-iac/tree/00033a7bd2a98bb07fb1c2cfa17a4cd85c6e0676/pkg/rego/schemas) schemas. Using a schema can help you validate your policy faster for syntax issues. | ||
| - `custom` is used to define custom fields that can be used by defsec to provide additional context to the policy and any related detections. This can contain the following: | ||
| - `avd_id` is the ID of the rule in the [AWS Vulnerability Database](https://avd.aquasec.com/). This is used to link the rule to the AVD entry. You can generate an ID to use for this field using `make id`. | ||
| - `provider` is the name of the provider the rule targets. This should be the same as the provider name in the `pkg/providers` directory, e.g. `aws`. | ||
| - `service` is the name of the service the rule targets. This should be the same as the service name in the `pkg/providers` directory, e.g. `rds`. | ||
| - `severity` is the severity of the rule. This should be one of `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`. | ||
| - `short_code` is a short code for the rule. This should be a short, descriptive name for the rule, separating words with hyphens. You should omit provider/service from this. | ||
| - `recommended_action` is a recommended remediation action for the rule. This should be a short, descriptive sentence describing what the user should do to resolve the issue. | ||
| - `input` tells _defsec_ what inputs this rule should be applied to. Cloud provider rules should always use the `selector` input, and should always use the `type` selector with `cloud`. Rules targeting Kubernetes yaml can use `kubenetes`, RBAC can use `rbac`, and so on. | ||
| - `subtypes` aid the engine to determine if it should load this policy or not for scanning. This can aid with the performance of scanning, especially if you have a lot of checks but not all apply to the IaC that you are trying to scan. | ||
|
|
||
| Now you'll need to write the rule logic. This is the code that will be executed to detect the issue. You should define a rule named `deny` and place your code inside this. | ||
|
|
||
| ```rego | ||
| deny[res] { | ||
| instance := input.aws.rds.instances[_] | ||
| instance.engine.value == ["postgres", "mysql"][_] | ||
| not instance.iamauthenabled.value | ||
| res := result.new("Instance does not have IAM Authentication enabled", instance.iamauthenabled) | ||
| } | ||
| ``` | ||
|
|
||
| The rule should return a result, which can be created using `result.new` (this function does not need to be imported, it is defined internally and provided at runtime). The first argument is the message to display, and the second argument is the resource that the issue was detected on. | ||
|
|
||
| In the example above, you'll notice properties are being accessed from the `input.aws` object. The full set of schemas containing all of these properties is [available here](https://github.com/aquasecurity/defsec/tree/master/pkg/rego/schemas). You can match the schema name to the type of input you want to scan. | ||
|
|
||
| You should also write a test for your rule(s). There are many examples of these in the `rules/cloud/policies` directory. | ||
|
|
||
| Finally, you'll want to generate documentation for your newly added rule. Please run `make docs` to within the [trivy-iac](https://github.com/aquasecurity/trivy-iac) repo generate the documentation for your new policy and submit a PR for us to take a look at. | ||
|
|
||
| You can see a full example PR for a new rule being added here: [https://github.com/aquasecurity/defsec/pull/1000](https://github.com/aquasecurity/defsec/pull/1000). |
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
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 |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| # trivy-policies | ||
|
|
||
| _trivy-policies_ contains misconfiguration checks for Trivy | ||
|
|
||
| Please see [ARCHITECTURE.md](ARCHITECTURE.md) for more information. | ||
|
|
||
| _trivy-aws_ is an [Aqua Security](https://aquasec.com) open source project. | ||
| Learn about our open source work and portfolio [here](https://www.aquasec.com/products/open-source-projects/). | ||
| Join the community, and talk to us about any matter in [GitHub Discussion](https://github.com/aquasecurity/trivy/discussions). |
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 |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| package main | ||
|
|
||
| import ( | ||
| "fmt" | ||
| "os" | ||
| "sort" | ||
| "strconv" | ||
| "strings" | ||
|
|
||
| "github.com/aquasecurity/defsec/pkg/framework" | ||
|
|
||
| _ "github.com/aquasecurity/trivy-iac/pkg/rego" | ||
| "github.com/aquasecurity/trivy-iac/pkg/rules" | ||
| ) | ||
|
|
||
| func main() { | ||
|
|
||
| // organise existing rules by provider | ||
| keyMap := make(map[string][]string) | ||
| for _, rule := range rules.GetRegistered(framework.ALL) { | ||
| id := rule.GetRule().AVDID | ||
| if id == "" { | ||
| continue | ||
| } | ||
| parts := strings.Split(id, "-") | ||
| if len(parts) != 3 { | ||
| continue | ||
| } | ||
| keyMap[parts[1]] = append(keyMap[parts[1]], parts[2]) | ||
| } | ||
|
|
||
| fmt.Print("\nThe following IDs are free - choose the one for the service you are targeting.\n\n") | ||
|
|
||
| var freeIDs []string | ||
| for key := range keyMap { | ||
| sort.Strings(keyMap[key]) | ||
| all := keyMap[key] | ||
| max := all[len(all)-1] | ||
| i, err := strconv.Atoi(max) | ||
| if err != nil { | ||
| _, _ = fmt.Fprintf(os.Stderr, "Error, invalid AVD ID: AVD-%s-%s\n", key, max) | ||
| } | ||
| free := fmt.Sprintf("AVD-%s-%04d", key, i+1) | ||
| freeIDs = append(freeIDs, fmt.Sprintf("%16s: %s", key, free)) | ||
| } | ||
|
|
||
| sort.Slice(freeIDs, func(i, j int) bool { | ||
| return strings.TrimSpace(freeIDs[i]) < strings.TrimSpace(freeIDs[j]) | ||
| }) | ||
| fmt.Println(strings.Join(freeIDs, "\n")) | ||
|
|
||
| } |
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
Oops, something went wrong.