github.com/khulnasoft-lab/defsec@v1.0.5-0.20230827010352-5e9f46893d95/ARCHITECTURE.md (about)

     1  # Architecture
     2  
     3  This document aims to answer the question *Where is the code that does X?*
     4  
     5  For more information please check out our [contributing guide](CONTRIBUTING.md).
     6  
     7  ## Overview
     8  
     9  The following diagram shows the high-level architecture of the project:
    10  
    11  ```mermaid
    12  graph TD;
    13      tf[Terraform]
    14      cf[CloudFormation]
    15      aws[Live AWS Account]
    16      k8s[Kubernetes YAML]
    17      df[Dockerfiles]
    18      k8sparser[Kubernetes Parser/Scanner]
    19      dfparser[Dockerfile Parser/Scanner]
    20      tfparser[Terraform Parser/Scanner]
    21      cfparser[CloudFormation Parser/Scanner]
    22      tfadapter[Terraform Adapter]
    23      cfadapter[CloudFormation Adapter]
    24      awsadapter[AWS Adapter]
    25      rules[Rules Engine]
    26      tf --> tfparser
    27      cf --> cfparser
    28      k8s --> k8sparser
    29      df --> dfparser
    30      tfparser --> tfadapter
    31      cfparser --> cfadapter
    32      aws --> awsadapter
    33      tfadapter --> rules
    34      cfadapter --> rules
    35      awsadapter --> rules
    36      k8sparser --> rules
    37      dfparser --> rules
    38  ```
    39  
    40  ## Scanning Overview
    41  
    42  The diagram below shows the process for parsing -> adapting -> scanning -> reporting.
    43  
    44  > Note: Source code files (Terraform, CloudFormation) come in on a filesystem. AWS cloud scanning is done with AWS Creds being passed by Vul
    45  
    46  
    47  
    48  ![Scanning Overview](.github/images/scanner_process.svg)
    49  
    50  ## Project Layout
    51  
    52  The directory structure is broken down as follows:
    53  
    54  - `avd_docs/` - The source for the [AVD documentation](https://khulnasoft-lab.github.io/avd/).
    55  - `cmd/` - The source for the `defsec` CLI. This CLI tool is primarily used during development for end-to-end testing without needing to pull the library into vul/terrasec etc.
    56  - `internal/adapters` - Adapters take input - such as a Terraform file or an AWS account - and _adapt_ it to a common format that can be used by the rules engine. This is where the bulk of the code is for supporting new cloud providers.
    57  - `rules` - All of the rules and policies are defined in this directory.
    58  - `pkg/detection` - Used for sniffing file types from both file name and content. This is done so that we can determine the type of file we're dealing with and then pass it to the correct parser.
    59  - `pkg/extrafs` - Wraps `os.DirFS` to provide a filesystem that can also resolve symlinks.
    60  - `pkg/formatters` - Used to format scan results in specific formats, such as JSON, CheckStyle, CSV, SARIF, etc.
    61  - `pkg/providers` - A series of data structures for describing cloud providers and their resources as a common schema.
    62  - `pkg/rego` - A package for evaluating Rego rules against given inputs.
    63  - `pkg/rules` - This package exposes internal rules, and imports them accordingly (see _rules.go_).
    64  - `pkg/scan` - Useful structs and functions for rules and scan results.
    65  - `pkg/scanners` - Scanners for various inputs. For example, the `terraform` scanner will scan a Terraform directory and return a list of resources.
    66  - `pkg/state` - The overall state object for Cloud providers is defined here. You should add to the `State` struct if you want to add a new cloud provider.
    67  - `pkg/terraform` - Data structures for describing Terraform resources and modules.
    68  - `pkg/types` - Useful types. Our types wrap a simple data type (e.g. `bool`) and add various metadata to it, such as file name and line number where it was defined.
    69  - `test` - Integration tests and other high-level tests that require a full build of the project.