diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml index 08eb6dc3a..420523b6e 100644 --- a/docs/mkdocs.yaml +++ b/docs/mkdocs.yaml @@ -130,10 +130,8 @@ nav: - api/extensions/containers.md - api/extensions/fetchers.md - api/extensions/format-conversion.md - - api/extensions/git.md - api/extensions/node.js.md - api/extensions/others.md - - api/extensions/patchers.md - api/extensions/python.md - api/extensions/ruby.md - versioning.md @@ -141,7 +139,7 @@ nav: - contributing.md - governance.md - Security: - - security/introduction.md + - security/index.md - security/assurance.md - security/design-principles.md - security/slsa.md diff --git a/docs/src/api/builtins/database.md b/docs/src/api/builtins/database.md index 3d1473bbd..33b0f9bc8 100644 --- a/docs/src/api/builtins/database.md +++ b/docs/src/api/builtins/database.md @@ -1,27 +1,27 @@ ## dynamoDb -Create a local dynamo database +Create local dynamo databases Types: - dynamoDb (`attrsOf targetType`): Optional. - Mapping of names to multiple databases. - Defaults to `{ }`. + Mapping of names to multiple databases. + Defaults to `{ }`. - targetType (`submodule`): - - name (`str`), - - host (`str`): Optional, defaults to `127.0.0.1`. - - port (`str`): Optional, defaults to `8022`. - - infra (`str`): Optional. Absolute path to the directory containing the - terraform infraestructure. - - daemonMode (`boolean`): Optional, defaults to `false`. - - data (`listOf str`): Optional, defaults to []. Absolute paths with json documents, - with the format defined for - [BatchWriteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html#API_BatchWriteItem_RequestSyntax). - - dataDerivation (`listOf package`): Optional, defaults to `[]`. - Derivations where the output ($ out), are json documents, - with the format defined for - [BatchWriteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html#API_BatchWriteItem_RequestSyntax). - This is useful if you want to perform transformations on your data. + - name (`str`), + - host (`str`): Optional, defaults to `127.0.0.1`. + - port (`str`): Optional, defaults to `8022`. + - infra (`str`): Optional. Absolute path to the directory containing the + terraform infrastructure. + - daemonMode (`boolean`): Optional, defaults to `false`. + - data (`listOf str`): Optional, defaults to []. Absolute paths with json documents, + with the format defined for + [BatchWriteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html#API_BatchWriteItem_RequestSyntax). + - dataDerivation (`listOf package`): Optional, defaults to `[]`. + Derivations where the output ($ out), are json documents, + with the format defined for + [BatchWriteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html#API_BatchWriteItem_RequestSyntax). + This is useful if you want to perform transformations on your data. Example: diff --git a/docs/src/api/builtins/deploy.md b/docs/src/api/builtins/deploy.md index 50f5db297..0b1130c5d 100644 --- a/docs/src/api/builtins/deploy.md +++ b/docs/src/api/builtins/deploy.md @@ -5,69 +5,68 @@ Submit a job to a [AWS BATCH](https://aws.amazon.com/batch/) queue. Types: - computeOnAwsBatch (`attrsOf jobType`): Optional. - Job groups to submit. - Defaults to `{ }`. -- jobType (`submodule`): - - - allowDuplicates (`bool`): Optional. - Set to `false` in order to prevent submitting the job - if there is already a job in the queue with the same name. - Defaults to `false`. - - attempts (`ints.positive`): Optional. - If the value of attempts is greater than one, - the job is retried on failure the same number of attempts as the value. - Defaults to `1`. - - attemptDurationSeconds (`ints.positive`): Optional. - The time duration in seconds - (measured from the job attempt's startedAt timestamp) - after which Batch terminates your jobs - if they have not finished. - - command (`listOf str`): - The command to send to the container. - It overrides the one specified - in the Batch job definition. - Additional arguments can be propagated when running this module output. - - definition (`str`): - Name of the Batch job definition - that we will use as base for submitting the job. - In general an Batch job definition is required - in order to specify which container image - our job is going to run on. - - environment (`listOf str`): Optional. - Name of the environment variables - whose names and values should be copied from the machine running Makes - to the machine on Batch running the job. - Defaults to `[ ]`. - - includePositionalArgsInName (`bool`): Optional. - Enable to make positional arguments part of the job name. - This is useful for identifying jobs - in the Batch console - more easily. - Defaults to `true`. - - memory (`ints.positive`): - Amount of memory, in MiB that is reserved for the job. - - parallel (`ints.positive`): Optional. - Number of parallel jobs to trigger using - [Batch Array Jobs](https://docs.aws.amazon.com/batch/latest/userguide/array_jobs.html). - - propagateTags (`bool`): Optional. - Enable tags to be propagated into the ECS tasks. - Defaults to `true`. - - queue (`nullOr str`): - Name of the Batch queue we should submit the job to. - It can be set to `null`, - causing Makes to read - the `MAKES_COMPUTE_ON_AWS_BATCH_QUEUE` environment variable at runtime. - - setup (`listOf package`): - [Makes Environment][makes_environment] - or [Makes Secrets][makes_secrets] - to `source` (as in Bash's `source`) - before anything else. - Defaults to `[ ]`. - - tags (`attrsOf str`): Optional. - Tags to apply to the batch job. + Job groups to submit. Defaults to `{ }`. - - vcpus (`ints.positive`): - Amount of virtual CPUs that is reserved for the job. +- jobType (`submodule`): + - allowDuplicates (`bool`): Optional. + Set to `false` in order to prevent submitting the job + if there is already a job in the queue with the same name. + Defaults to `false`. + - attempts (`ints.positive`): Optional. + If the value of attempts is greater than one, + the job is retried on failure the same number of attempts as the value. + Defaults to `1`. + - attemptDurationSeconds (`ints.positive`): Optional. + The time duration in seconds + (measured from the job attempt's startedAt timestamp) + after which Batch terminates your jobs + if they have not finished. + - command (`listOf str`): + The command to send to the container. + It overrides the one specified + in the Batch job definition. + Additional arguments can be propagated when running this module output. + - definition (`str`): + Name of the Batch job definition + that we will use as base for submitting the job. + In general an Batch job definition is required + in order to specify which container image + our job is going to run on. + - environment (`listOf str`): Optional. + Name of the environment variables + whose names and values should be copied from the machine running Makes + to the machine on Batch running the job. + Defaults to `[ ]`. + - includePositionalArgsInName (`bool`): Optional. + Enable to make positional arguments part of the job name. + This is useful for identifying jobs + in the Batch console + more easily. + Defaults to `true`. + - memory (`ints.positive`): + Amount of memory, in MiB that is reserved for the job. + - parallel (`ints.positive`): Optional. + Number of parallel jobs to trigger using + [Batch Array Jobs](https://docs.aws.amazon.com/batch/latest/userguide/array_jobs.html). + - propagateTags (`bool`): Optional. + Enable tags to be propagated into the ECS tasks. + Defaults to `true`. + - queue (`nullOr str`): + Name of the Batch queue we should submit the job to. + It can be set to `null`, + causing Makes to read + the `MAKES_COMPUTE_ON_AWS_BATCH_QUEUE` environment variable at runtime. + - setup (`listOf package`): + [Makes Environment][makes_environment] + or [Makes Secrets][makes_secrets] + to `source` (as in Bash's `source`) + before anything else. + Defaults to `[ ]`. + - tags (`attrsOf str`): Optional. + Tags to apply to the batch job. + Defaults to `{ }`. + - vcpus (`ints.positive`): + Amount of virtual CPUs that is reserved for the job. Example: @@ -122,33 +121,33 @@ please read the `makeContainerImage` reference. Types: - deployContainerImage: - - images (`attrsOf imageType`): Optional. - Definitions of container images to deploy. - Defaults to `{ }`. + - images (`attrsOf imageType`): Optional. + Definitions of container images to deploy. + Defaults to `{ }`. - imageType (`submodule`): - - attempts (`ints.positive`): Optional. - If the value of attempts is greater than one, - the job is retried on failure the same number of attempts as the value. - Defaults to `1`. - - credentials: - - token (`str`): - Name of the environment variable - that stores the value of the registry token. - - user (`str`): - Name of the environment variable - that stores the value of the registry user. - - registry (`str`): - Registry in which the image will be copied to. - - setup (`listOf package`): Optional. - [Makes Environment][makes_environment] - or [Makes Secrets][makes_secrets] - to `source` (as in Bash's `source`) - before anything else. - Defaults to `[ ]`. - - src (`package`): - Derivation that contains the container image in OCI Format. - - tag (`str`): - The tag under which the image will be stored in the registry. + - attempts (`ints.positive`): Optional. + If the value of attempts is greater than one, + the job is retried on failure the same number of attempts as the value. + Defaults to `1`. + - credentials: + - token (`str`): + Name of the environment variable + that stores the value of the registry token. + - user (`str`): + Name of the environment variable + that stores the value of the registry user. + - registry (`str`): + Registry in which the image will be copied to. + - setup (`listOf package`): Optional. + [Makes Environment][makes_environment] + or [Makes Secrets][makes_secrets] + to `source` (as in Bash's `source`) + before anything else. + Defaults to `[ ]`. + - src (`package`): + Derivation that contains the container image in OCI Format. + - tag (`str`): + The tag under which the image will be stored in the registry. Example: @@ -228,20 +227,20 @@ over the specified Terraform modules. Types: - deployTerraform: - - modules (`attrsOf moduleType`): Optional. - Path to Terraform modules to lint. - Defaults to `{ }`. + - modules (`attrsOf moduleType`): Optional. + Path to Terraform modules to lint. + Defaults to `{ }`. - moduleType (`submodule`): - - setup (`listOf package`): Optional. - [Makes Environment][makes_environment] - or [Makes Secrets][makes_secrets] - to `source` (as in Bash's `source`) - before anything else. - Defaults to `[ ]`. - - src (`str`): - Path to the Terraform module. - - version (`enum [ "0.14" "0.15" "1.0" ]`): - Terraform version your module is built with. + - setup (`listOf package`): Optional. + [Makes Environment][makes_environment] + or [Makes Secrets][makes_secrets] + to `source` (as in Bash's `source`) + before anything else. + Defaults to `[ ]`. + - src (`str`): + Path to the Terraform module. + - version (`enum [ "0.14" "0.15" "1.0" ]`): + Terraform version your module is built with. Example: @@ -279,25 +278,25 @@ over the specified Terraform modules. Types: - taintTerraform: - - modules (`attrsOf moduleType`): Optional. - Path to Terraform modules to lint. - Defaults to `{ }`. + - modules (`attrsOf moduleType`): Optional. + Path to Terraform modules to lint. + Defaults to `{ }`. - moduleType (`submodule`): - - reDeploy (`bool`): Optional. - Perform a `terraform apply` after tainting resources. - Defaults to `false`. - - resources (`listOf str`): - Resources to taint. - - setup (`listOf package`): Optional. - [Makes Environment][makes_environment] - or [Makes Secrets][makes_secrets] - to `source` (as in Bash's `source`) - before anything else. - Defaults to `[ ]`. - - src (`str`): - Path to the Terraform module. - - version (`enum [ "0.14" "0.15" "1.0" ]`): - Terraform version your module is built with. + - reDeploy (`bool`): Optional. + Perform a `terraform apply` after tainting resources. + Defaults to `false`. + - resources (`listOf str`): + Resources to taint. + - setup (`listOf package`): Optional. + [Makes Environment][makes_environment] + or [Makes Secrets][makes_secrets] + to `source` (as in Bash's `source`) + before anything else. + Defaults to `[ ]`. + - src (`str`): + Path to the Terraform module. + - version (`enum [ "0.14" "0.15" "1.0" ]`): + Terraform version your module is built with. Example: @@ -332,38 +331,38 @@ over the specified Nomad jobs / namespaces. Types: - deployNomad: - - jobs (`attrsOf jobsType`): Optional. - Path to Nomad jobs to deploy. - Defaults to `{ }`. - - namespaces (`attrsOf namespacesType`): Optional. - Path to Nomad namespaces to deploy. - Defaults to `{ }`. + - jobs (`attrsOf jobsType`): Optional. + Path to Nomad jobs to deploy. + Defaults to `{ }`. + - namespaces (`attrsOf namespacesType`): Optional. + Path to Nomad namespaces to deploy. + Defaults to `{ }`. - jobsType (`submodule`): - - setup (`listOf package`): Optional. - [Makes Environment][makes_environment] - or [Makes Secrets][makes_secrets] - to `source` (as in Bash's `source`) - before anything else. - Defaults to `[ ]`. - - src (`path`): - Path to the Nomad job (hcl or json). - - version (`enum [ "1.0" "1.1" ]`): - Nomad version your job is built with. - Defaults to `"1.1"`. - - namespace (`str`): - Nomad namespace to deploy the job into. + - setup (`listOf package`): Optional. + [Makes Environment][makes_environment] + or [Makes Secrets][makes_secrets] + to `source` (as in Bash's `source`) + before anything else. + Defaults to `[ ]`. + - src (`path`): + Path to the Nomad job (hcl or json). + - version (`enum [ "1.0" "1.1" ]`): + Nomad version your job is built with. + Defaults to `"1.1"`. + - namespace (`str`): + Nomad namespace to deploy the job into. - namespacesType (`submodule`): - - setup (`listOf package`): Optional. - Makes Environment - or Makes Secrets - to `source` (as in Bash's `source`) - before anything else. - Defaults to `[ ]`. - - jobs (`attrOf path`): - Attributes of path to the Nomad jobs (hcl or json). - - version (`enum [ "1.0" "1.1" ]`): - Nomad version your jobs are built with. - Defaults to `"1.1"`. + - setup (`listOf package`): Optional. + Makes Environment + or Makes Secrets + to `source` (as in Bash's `source`) + before anything else. + Defaults to `[ ]`. + - jobs (`attrOf path`): + Attributes of path to the Nomad jobs (hcl or json). + - version (`enum [ "1.0" "1.1" ]`): + Nomad version your jobs are built with. + Defaults to `"1.1"`. Example: diff --git a/docs/src/api/builtins/development.md b/docs/src/api/builtins/development.md index b5a7b8d0b..ca90531ec 100644 --- a/docs/src/api/builtins/development.md +++ b/docs/src/api/builtins/development.md @@ -9,8 +9,8 @@ the development environment and its required dependencies. Types: - dev (`attrsOf (asIn makeSearchPaths)`): Optional. - Mapping of environment name to searchPaths. - Defaults to `{ }`. + Mapping of environment name to searchPaths. + Defaults to `{ }`. Example: diff --git a/docs/src/api/builtins/environment.md b/docs/src/api/builtins/environment.md index b3aaa018a..3fcadfbce 100644 --- a/docs/src/api/builtins/environment.md +++ b/docs/src/api/builtins/environment.md @@ -10,7 +10,8 @@ Allows you to map environment variables from a name to a value. Types: - envVars (`attrsOf (attrsOf str)`): Optional. - Defaults to `{ }`. + + Defaults to `{ }`. Example: @@ -61,7 +62,8 @@ Allows you to map Terraform variables from a name to a value. Types: - envVarsForTerraform (`attrsOf (attrsOf str)`): Optional. - Defaults to `{ }`. + + Defaults to `{ }`. Example: diff --git a/docs/src/api/builtins/examples.md b/docs/src/api/builtins/examples.md index e2a1f0c76..b979aa1be 100644 --- a/docs/src/api/builtins/examples.md +++ b/docs/src/api/builtins/examples.md @@ -5,10 +5,10 @@ Small command for demo purposes, it greets the specified user: Types: - helloWorld: - - enable (`boolean`): Optional. - Defaults to `false`. - - name (`string`): - Name of the user we should greet. + - enable (`boolean`): Optional. + Defaults to `false`. + - name (`string`): + Name of the user we should greet. Example: diff --git a/docs/src/api/builtins/format.md b/docs/src/api/builtins/format.md index 963049212..734cf6be7 100644 --- a/docs/src/api/builtins/format.md +++ b/docs/src/api/builtins/format.md @@ -8,11 +8,11 @@ according to [shfmt](https://github.com/mvdan/sh). Types: - formatBash: - - enable (`boolean`): Optional. - Defaults to false. - - targets (`listOf str`): Optional. - Files or directories (relative to the project) to format. - Defaults to the entire project. + - enable (`boolean`): Optional. + Defaults to false. + - targets (`listOf str`): Optional. + Files or directories (relative to the project) to format. + Defaults to the entire project. Example: @@ -49,13 +49,13 @@ according to [doctoc](https://github.com/thlorenz/doctoc). Types: - formatMarkdown: - - enable (`boolean`): Optional. - Defaults to `false`. - - doctocArgs (`listOf str`): Optional. - Extra CLI flags to propagate to doctoc. - Defaults to `[ ]`. - - targets (`listOf str`): - Files (relative to the project) to format. + - enable (`boolean`): Optional. + Defaults to `false`. + - doctocArgs (`listOf str`): Optional. + Extra CLI flags to propagate to doctoc. + Defaults to `[ ]`. + - targets (`listOf str`): + File s (relative to the project) to format. Example: @@ -85,11 +85,11 @@ according to [Alejandra](https://github.com/kamadorueda/alejandra). Types: - formatNix: - - enable (`boolean`): Optional. - Defaults to `false`. - - targets (`listOf str`): Optional. - Files or directories (relative to the project) to format. - Defaults to the entire project. + - enable (`boolean`): Optional. + Defaults to `false`. + - targets (`listOf str`): Optional. + Files or directories (relative to the project) to format. + Defaults to the entire project. Example: @@ -123,11 +123,11 @@ and [isort](https://github.com/PyCQA/isort). Types: - formatPython: - - enable (`boolean`): Optional. - Defaults to `false`. - - targets (`listOf str`): Optional. - Files or directories (relative to the project) to format. - Defaults to the entire project. + - enable (`boolean`): Optional. + Defaults to `false`. + - targets (`listOf str`): Optional. + Files or directories (relative to the project) to format. + Defaults to the entire project. Example: @@ -160,11 +160,11 @@ according to [Terraform FMT](https://www.terraform.io/docs/cli/commands/fmt.html Types: - formatTerraform: - - enable (`boolean`): Optional. - Defaults to `false`. - - targets (`listOf str`): Optional. - Files or directories (relative to the project) to format. - Defaults to the entire project. + - enable (`boolean`): Optional. + Defaults to `false`. + - targets (`listOf str`): Optional. + Files or directories (relative to the project) to format. + Defaults to the entire project. Example: @@ -197,11 +197,11 @@ is formatted according to [yamlfix](https://github.com/lyz-code/yamlfix). Types: - formatYaml: - - enable (`boolean`): Optional. - Defaults to `false`. - - targets (`listOf str`): Optional. - Files or directories (relative to the project) to format. - Defaults to the entire project. + - enable (`boolean`): Optional. + Defaults to `false`. + - targets (`listOf str`): Optional. + Files or directories (relative to the project) to format. + Defaults to the entire project. Example: diff --git a/docs/src/api/builtins/framework-configuration.md b/docs/src/api/builtins/framework-configuration.md index 412344215..c96ceecdc 100644 --- a/docs/src/api/builtins/framework-configuration.md +++ b/docs/src/api/builtins/framework-configuration.md @@ -5,7 +5,19 @@ Paths to magic directories where Makes extensions will be loaded from. Types: - extendingMakesDirs (`listOf str`): Optional. - Defaults to `["/makes"]`. + + Defaults to `["/makes"]`. + +Example: + +=== "makes.nix" + + ```nix + { + # Look for main.nix files everywhere in the repo. + extendingMakesDirs = ["/"]; + } + ``` ## inputs @@ -15,7 +27,8 @@ Inputs can be anything. Types: - inputs (`attrOf anything`): Optional. - Defaults to `{ }`. + + Defaults to `{ }`. Example: diff --git a/docs/src/api/builtins/index.md b/docs/src/api/builtins/index.md index 8d44e7c31..d5b8ca23c 100644 --- a/docs/src/api/builtins/index.md +++ b/docs/src/api/builtins/index.md @@ -7,34 +7,34 @@ A `makes.nix` file should be: - An attribute set of configuration options: - ```nix - { - configOption1 = { - # ... - }; - configOption2 = { - # ... - }; - } - ``` + ```nix + { + configOption1 = { + # ... + }; + configOption2 = { + # ... + }; + } + ``` - A function that receives one or more arguments and returns an attribute set of configuration options: - ```nix - { - argA, - argB, - ... - }: { - configOption1 = { - # ... - }; - configOption2 = { - # ... - }; - } - ``` + ```nix + { + argA, + argB, + ... + }: { + configOption1 = { + # ... + }; + configOption2 = { + # ... + }; + } + ``` In the next sections we document all configuration options diff --git a/docs/src/api/builtins/lint.md b/docs/src/api/builtins/lint.md index 712d8ddd1..7bd079389 100644 --- a/docs/src/api/builtins/lint.md +++ b/docs/src/api/builtins/lint.md @@ -8,11 +8,11 @@ Lints Bash code with [ShellCheck](https://github.com/koalaman/shellcheck). Types: - lintBash: - - enable (`boolean`): Optional. - Defaults to `false`. - - targets (`listOf str`): Optional. - Files or directories (relative to the project) to lint. - Defaults to the entire project. + - enable (`boolean`): Optional. + Defaults to `false`. + - targets (`listOf str`): Optional. + Files or directories (relative to the project) to lint. + Defaults to the entire project. Example: @@ -44,8 +44,9 @@ Lints clojure code with [clj-kondo](https://github.com/clj-kondo/clj-kondo). Types: - lintClojure (`attrsOf (listOf str)`): Optional. - Mapping of custom names to lists of paths (relative to the project) to lint. - Defaults to `{ }`. + Mapping of custom names to lists of paths (relative to the project) to lint. + + Defaults to `{ }`. Example: @@ -86,19 +87,19 @@ are linted using [Commitlint](https://commitlint.js.org/#/). Types: - lintGitCommitMsg: - - enable (`boolean`): Optional. - Defaults to `false`. - - branch (`str`): Optional. - Name of the main branch. - Defaults to `main`. - - config (`str`): Optional. - Path to a configuration file for Commitlint. - Defaults to - [config.js](/src/evaluator/modules/lint-git-commit-msg/config.js). - - parser (`str`): Optional. - Commitlint parser definitions. - Defaults to - [parser.js](/src/evaluator/modules/lint-git-commit-msg/parser.js). + - enable (`boolean`): Optional. + Defaults to `false`. + - branch (`str`): Optional. + Name of the main branch. + Defaults to `main`. + - config (`str`): Optional. + Path to a configuration file for Commitlint. + Defaults to + [config.js](/src/evaluator/modules/lint-git-commit-msg/config.js). + - parser (`str`): Optional. + Commitlint parser definitions. + Defaults to + [parser.js](/src/evaluator/modules/lint-git-commit-msg/parser.js). Example: @@ -131,8 +132,8 @@ of the project with Types: - lintGitMailmap: - - enable (`boolean`): Optional. - Defaults to `false`. + - enable (`boolean`): Optional. + Defaults to `false`. Example: @@ -159,14 +160,14 @@ Lints Markdown code with [Markdown lint tool](https://github.com/markdownlint/ma Types: - lintMarkdown (`attrsOf moduleType`): Optional. - Definitions of config and associated paths to lint. - Defaults to `{ }`. + Definitions of config and associated paths to lint. + Defaults to `{ }`. - moduleType (`submodule`): - - config (`str`): Optional. - Path to the config file. - Defaults to [config.rb](/src/evaluator/modules/lint-markdown/config.rb). - - targets (`listOf str`): Required. - paths to lint with `config`. + - config (`str`): Optional. + Path to the config file. + Defaults to [config.rb](/src/evaluator/modules/lint-markdown/config.rb). + - targets (`listOf str`): Required. + paths to lint with `config`. Example: @@ -200,11 +201,11 @@ Lints Nix code with [nix-linter](https://github.com/Synthetica9/nix-linter). Types: - lintNix: - - enable (`boolean`): Optional. - Defaults to `false`. - - targets (`listOf str`): Optional. - Files or directories (relative to the project) to lint. - Defaults to the entire project. + - enable (`boolean`): Optional. + Defaults to `false`. + - targets (`listOf str`): Optional. + Files or directories (relative to the project) to lint. + Defaults to the entire project. Example: @@ -238,39 +239,39 @@ and (if configured) [import-linter](https://import-linter.readthedocs.io/en/stab Types: - lintPython: - - dirsOfModules (`attrsOf dirOfModulesType`): Optional. - Definitions of directories of python packages/modules to lint. - Defaults to `{ }`. - - imports (`attrsOf importsType`): Optional. - Definitions of python packages whose imports will be linted. - Defaults to `{ }`. - - modules (`attrsOf moduleType`): Optional. - Definitions of python packages/modules to lint. - Defaults to `{ }`. + - dirsOfModules (`attrsOf dirOfModulesType`): Optional. + Definitions of directories of python packages/modules to lint. + Defaults to `{ }`. + - imports (`attrsOf importsType`): Optional. + Definitions of python packages whose imports will be linted. + Defaults to `{ }`. + - modules (`attrsOf moduleType`): Optional. + Definitions of python packages/modules to lint. + Defaults to `{ }`. - dirOfModulesType (`submodule`): - - python (`enum ["3.8" "3.9" "3.10" "3.11"]`): - Python interpreter version that your package/module is designed for. - - searchPaths (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths`. - Defaults to `makeSearchPaths`'s defaults. - - src (`str`): - Path to the directory that contains inside many packages/modules. + - python (`enum ["3.8" "3.9" "3.10" "3.11"]`): + Python interpreter version that your package/module is designed for. + - searchPaths (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths`. + Defaults to `makeSearchPaths`'s defaults. + - src (`str`): + Path to the directory that contains inside many packages/modules. - importsType (`submodule`): - - config (`str`): - Path to the import-linter configuration file. - - searchPaths (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths`. - Defaults to `makeSearchPaths`'s defaults. - - src (`str`): - Path to the package/module. + - config (`str`): + Path to the import-linter configuration file. + - searchPaths (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths`. + Defaults to `makeSearchPaths`'s defaults. + - src (`str`): + Path to the package/module. - moduleType (`submodule`): - - python (`enum ["3.8" "3.9" "3.10" "3.11"]`): - Python interpreter version that your package/module is designed for. - - searchPaths (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths`. - Defaults to `makeSearchPaths`'s defaults. - - src (`str`): - Path to the package/module. + - python (`enum ["3.8" "3.9" "3.10" "3.11"]`): + Python interpreter version that your package/module is designed for. + - searchPaths (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths`. + Defaults to `makeSearchPaths`'s defaults. + - src (`str`): + Path to the package/module. Example: @@ -321,23 +322,23 @@ with [TFLint](https://github.com/terraform-linters/tflint). Types: - lintTerraform: - - config (`str`): Optional. - Path to a TFLint configuration file. - Defaults to [config.hcl](/src/evaluator/modules/lint-terraform/config.hcl). - - modules (`attrsOf moduleType`): Optional. - Path to Terraform modules to lint. - Defaults to `{ }`. + - config (`str`): Optional. + Path to a TFLint configuration file. + Defaults to [config.hcl](/src/evaluator/modules/lint-terraform/config.hcl). + - modules (`attrsOf moduleType`): Optional. + Path to Terraform modules to lint. + Defaults to `{ }`. - moduleType (`submodule`): - - setup (`listOf package`): Optional. - [Makes Environment](./environment.md) - or [Makes Secrets](./secrets.md) - to `source` (as in Bash's `source`) - before anything else. - Defaults to `[ ]`. - - src (`str`): - Path to the Terraform module. - - version (`enum [ "0.14" "0.15" "1.0" ]`): - Terraform version your module is built with. + - setup (`listOf package`): Optional. + [Makes Environment](./environment.md) + or [Makes Secrets](./secrets.md) + to `source` (as in Bash's `source`) + before anything else. + Defaults to `[ ]`. + - src (`str`): + Path to the Terraform module. + - version (`enum [ "0.14" "0.15" "1.0" ]`): + Terraform version your module is built with. Example: @@ -381,14 +382,14 @@ It uses [ajv-cli](https://github.com/ajv-validator/ajv-cli). Types: - lintWithAjv (`attrsOf schemaType`): Optional. - Definitions of schema and associated data to lint. - Defaults to `{ }`. + Definitions of schema and associated data to lint. + Defaults to `{ }`. - schemaType (`submodule`): - - schema (`str`): Required. - Path to the JSON Schema. - - targets (`listOf str`): Required. - YAML or JSON - data files to lint with `schema`. + - schema (`str`): Required. + Path to the JSON Schema. + - targets (`listOf str`): Required. + YAML or JSON + data files to lint with `schema`. Example: @@ -430,8 +431,9 @@ in all supported languages Types: - lintWithLizard (`attrsOf (listOf str)`): Optional. - Mapping of custom names to lists of paths (relative to the project) to lint. - Defaults to `{ }`. + Mapping of custom names to lists of paths (relative to the project) to lint. + + Defaults to `{ }`. Example: diff --git a/docs/src/api/builtins/monitoring.md b/docs/src/api/builtins/monitoring.md index 66c3d33ec..47d6ef7be 100644 --- a/docs/src/api/builtins/monitoring.md +++ b/docs/src/api/builtins/monitoring.md @@ -7,42 +7,42 @@ available for [GitHub](https://github.com) projects at the moment. Pre-requisites: 1. To run this module you need to set up a valid `GITHUB_AUTH_TOKEN` on your - target repository. You can set this up in your CI or locally to run this - check on your machine. + target repository. You can set this up in your CI or locally to run this + check on your machine. Types: - checks (`listOf str`): Optional, - defaults to all the checks available for Scorecard: + defaults to all the checks available for Scorecard: - ```nix - [ - "Branch-Protection" - "Fuzzing" - "License" - "SAST" - "Binary-Artifacts" - "Dependency-Update-Tool" - "Pinned-Dependencies" - "CI-Tests" - "Code-Review" - "Contributors" - "Maintained" - "Token-Permissions" - "Security-Policy" - "CII-Best-Practices" - "Dangerous-Workflow" - "Packaging" - "Signed-Releases" - "Vulnerabilities" - ] - ``` + ```nix + [ + "Branch-Protection" + "Fuzzing" + "License" + "SAST" + "Binary-Artifacts" + "Dependency-Update-Tool" + "Pinned-Dependencies" + "CI-Tests" + "Code-Review" + "Contributors" + "Maintained" + "Token-Permissions" + "Security-Policy" + "CII-Best-Practices" + "Dangerous-Workflow" + "Packaging" + "Signed-Releases" + "Vulnerabilities" + ] + ``` - format (`str`): Optional, defaults to JSON. This is the format which - the scorecard will be printed. Accepted values are: `"default"` which is an - `ASCII Table` and JSON. + the scorecard will be printed. Accepted values are: `"default"` which is an + `ASCII Table` and JSON. - target (`str`): Mandatory, this is the repository url where you want to run - scorecard. + scorecard. Example: diff --git a/docs/src/api/builtins/performance.md b/docs/src/api/builtins/performance.md index a4f3ca267..8975deb8a 100644 --- a/docs/src/api/builtins/performance.md +++ b/docs/src/api/builtins/performance.md @@ -6,29 +6,29 @@ and optionally a [Cachix](https://cachix.org/) cache for reading and writting. Types: - cache: - - extra: (attrsOf (cacheExtra)) - - readNixos (`bool`): Optional. - Set to `true` in order to add https://cache.nixos.org as a read cache. - Defaults to `true`. + - extra: (attrsOf cacheExtra) + - readNixos (`bool`): Optional. + Set to `true` in order to add https://cache.nixos.org as a read cache. + Defaults to `true`. - cacheExtra: - - enable (`str`): Read from cache. - is read on the server. - - pubKey (`str`): Public key of the cache server. - - token (`str`): The name of the environment variable that contains the - token to push the cache. - - type: (`enum [cachix]`): Binary cache type. - Can be [Cachix](https://docs.cachix.org/). - - url (`str`): - URL of the cache. - - write (`bool`): Enable pushing derivations to the cache. Requires `token`. + - enable (`str`): Read from cache. + is read on the server. + - pubKey (`str`): Public key of the cache server. + - token (`str`): The name of the environment variable that contains the + token to push the cache. + - type: (`enum [cachix]`): Binary cache type. + Can be [Cachix](https://docs.cachix.org/). + - url (`str`): + URL of the cache. + - write (`bool`): Enable pushing derivations to the cache. Requires `token`. Required environment variables: - `CACHIX_AUTH_TOKEN`: API token of the Cachix cache. - - For Public caches: - If not set the cache will be read, but not written to. - - For private caches: - If not set the cache won't be read, nor written to. + - For Public caches: + If not set the cache will be read, but not written to. + - For private caches: + If not set the cache won't be read, nor written to. Example: diff --git a/docs/src/api/builtins/secrets.md b/docs/src/api/builtins/secrets.md index 9a34533a8..2ab843ac9 100644 --- a/docs/src/api/builtins/secrets.md +++ b/docs/src/api/builtins/secrets.md @@ -12,36 +12,32 @@ from environment variables. Types: - secretsForAwsFromEnv (`attrsOf awsFromEnvType`): Optional. - Defaults to `{ }`. + Defaults to `{ }`. - awsFromEnvType (`submodule`): - - - accessKeyId (`str`): Optional. - Name of the environment variable - that stores the value of the AWS Access Key Id. - Defaults to `"AWS_ACCESS_KEY_ID"`. - - - defaultRegion (`str`): Optional. - Name of the environment variable - that stores the value of the AWS Default Region. - Defaults to `"AWS_DEFAULT_REGION"` (Which defaults to `"us-east-1"`). - - - secretAccessKey (`str`): Optional. - Name of the environment variable - that stores the value of the AWS Secret Access Key. - Defaults to `"AWS_SECRET_ACCESS_KEY"`. - - - sessionToken (`str`): Optional. - Name of the environment variable - that stores the value of the AWS Session Token. - Defaults to `"AWS_SESSION_TOKEN"` (Which defaults to `""`). + - accessKeyId (`str`): Optional. + Name of the environment variable + that stores the value of the AWS Access Key Id. + Defaults to `"AWS_ACCESS_KEY_ID"`. + - defaultRegion (`str`): Optional. + Name of the environment variable + that stores the value of the AWS Default Region. + Defaults to `"AWS_DEFAULT_REGION"` (Which defaults to `"us-east-1"`). + - secretAccessKey (`str`): Optional. + Name of the environment variable + that stores the value of the AWS Secret Access Key. + Defaults to `"AWS_SECRET_ACCESS_KEY"`. + - sessionToken (`str`): Optional. + Name of the environment variable + that stores the value of the AWS Session Token. + Defaults to `"AWS_SESSION_TOKEN"` (Which defaults to `""`). Always available outputs: - `/secretsForAwsFromEnv/__default__`: - - accessKeyId: "AWS_ACCESS_KEY_ID"; - - defaultRegion: "AWS_DEFAULT_REGION"; - - secretAccessKey: "AWS_SECRET_ACCESS_KEY"; - - sessionToken: "AWS_SESSION_TOKEN"; + - accessKeyId: "AWS_ACCESS_KEY_ID"; + - defaultRegion: "AWS_DEFAULT_REGION"; + - secretAccessKey: "AWS_SECRET_ACCESS_KEY"; + - sessionToken: "AWS_SESSION_TOKEN"; Example: @@ -93,20 +89,17 @@ using [GitLab CI OIDC](https://docs.gitlab.com/ee/ci/cloud_services/aws/index.ht Types: - secretsForAwsFromGitlab (`attrsOf awsFromGitlabType`): Optional. - Defaults to `{ }`. + Defaults to `{ }`. - awsFromGitlabType (`submodule`): - - - roleArn (`str`): - ARN of AWS role to be assumed. - - - duration (`ints.positive`): Optional. - Duration in seconds of the session. - Defaults to `3600`. - - - retries (`ints.positive`): Optional. - Number of login retries before failing. - One retry per second. - Defaults to `15`. + - roleArn (`str`): + ARN of AWS role to be assumed. + - duration (`ints.positive`): Optional. + Duration in seconds of the session. + Defaults to `3600`. + - retries (`ints.positive`): Optional. + Number of login retries before failing. + One retry per second. + Defaults to `15`. Example: @@ -160,12 +153,12 @@ to environment variables. Types: - secretsForEnvFromSops (`attrsOf secretForEnvFromSopsType`): Optional. - Defaults to `{ }`. + Defaults to `{ }`. - secretForEnvFromSopsType (`submodule`): - - manifest (`str`): - Relative path to the encrypted Sops file. - - vars (`listOf str`): - Names of the values to export out of the manifest. + - manifest (`str`): + Relative path to the encrypted Sops file. + - vars (`listOf str`): + Names of the values to export out of the manifest. Example: @@ -212,10 +205,10 @@ in [ASCII Armor](https://www.techopedia.com/definition/23150/ascii-armor) format Types: - secretsForGpgFromEnv (`attrsOf (listOf str)`): Optional. - Mapping of name - to a list of environment variable names - where the GPG key contents are stored. - Defaults to `{ }`. + Mapping of name + to a list of environment variable names + where the GPG key contents are stored. + Defaults to `{ }`. Example: @@ -293,13 +286,13 @@ and set it up in the Types: - secretsForKubernetesConfigFromAws - (`attrsOf secretForKubernetesConfigFromAwsType`): Optional. - Defaults to `{ }`. + (`attrsOf secretForKubernetesConfigFromAwsType`): Optional. + Defaults to `{ }`. - secretForKubernetesConfigFromAwsType (`submodule`): - - cluster (`str`): - AWS EKS Cluster name. - - region (`str`): - AWS Region the EKS cluster is located in. + - cluster (`str`): + AWS EKS Cluster name. + - region (`str`): + AWS Region the EKS cluster is located in. Example: @@ -338,10 +331,10 @@ from the given environment variables. Types: - secretsForTerraformFromEnv (`attrsOf (attrsOf str)`): Optional. - Mapping of secrets group name - to a mapping of Terraform variable names - to environment variable names. - Defaults to `{ }`. + Mapping of secrets group name + to a mapping of Terraform variable names + to environment variable names. + Defaults to `{ }`. Example: diff --git a/docs/src/api/builtins/security.md b/docs/src/api/builtins/security.md index 2fbc7facf..20d84d606 100644 --- a/docs/src/api/builtins/security.md +++ b/docs/src/api/builtins/security.md @@ -10,19 +10,17 @@ with [rbac-police](https://github.com/PaloAltoNetworks/rbac-police). Types: - secureKubernetesWithRbacPolice (`attrsOf kubernetesWithRbacPolice`): Optional. - Defaults to `{ }`. + Defaults to `{ }`. - kubernetesWithRbacPolice (`submodule`): - - - severity (`str`): - Only evaluate policies with severity >= threshold. - Defaults to `Low`. - - - setup (`listOf package`): - [Makes Environment](./environment.md) - or [Makes Secrets](./secrets.md) - to `source` (as in Bash's `source`) - before anything else. - Defaults to `[ ]`. + - severity (`str`): + Only evaluate policies with severity >= threshold. + Defaults to `Low`. + - setup (`listOf package`): + [Makes Environment](./environment.md) + or [Makes Secrets](./secrets.md) + to `source` (as in Bash's `source`) + before anything else. + Defaults to `[ ]`. Example: @@ -75,13 +73,13 @@ with [Bandit](https://github.com/PyCQA/bandit). Types: - securePythonWithBandit (`attrsOf projectType`): Optional. - Definitions of directories of python packages/modules to lint. - Defaults to `{ }`. + Definitions of directories of python packages/modules to lint. + Defaults to `{ }`. - projectType (`submodule`): - - python (`enum ["3.8" "3.9" "3.10" "3.11"]`): - Python interpreter version that your package/module is designed for. - - target (`str`): - Relative path to the package/module. + - python (`enum ["3.8" "3.9" "3.10" "3.11"]`): + Python interpreter version that your package/module is designed for. + - target (`str`): + Relative path to the package/module. Example: diff --git a/docs/src/api/builtins/test.md b/docs/src/api/builtins/test.md index b72d52482..0707c5968 100644 --- a/docs/src/api/builtins/test.md +++ b/docs/src/api/builtins/test.md @@ -6,23 +6,22 @@ with [pytest](https://docs.pytest.org/). Types: - testPython (`attrsOf targetType`): Optional. - Mapping of names to pytest targets. - Defaults to `{ }`. + Mapping of names to pytest targets. + Defaults to `{ }`. - targetType (`submodule`): - - - python (`enum ["3.8" "3.9" "3.10" "3.11"]`): - Python interpreter version that your package/module is designed for. - - src (`str`): - Path to the file or directory that contains the tests code. - - searchPaths (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths`. - Defaults to `makeSearchPaths`'s defaults. - - extraFlags (`listOf str`): Optional. - Extra command line arguments to propagate to pytest. - Defaults to `[ ]`. - - extraSrcs (`attrsOf package`): Optional. - Place extra sources at the same level of your project code - so you can reference them via relative paths. + - python (`enum ["3.8" "3.9" "3.10" "3.11"]`): + Python interpreter version that your package/module is designed for. + - src (`str`): + Path to the file or directory that contains the tests code. + - searchPaths (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths`. + Defaults to `makeSearchPaths`'s defaults. + - extraFlags (`listOf str`): Optional. + Extra command line arguments to propagate to pytest. + Defaults to `[ ]`. + - extraSrcs (`attrsOf package`): Optional. + Place extra sources at the same level of your project code + so you can reference them via relative paths. The final test structure looks like this: @@ -89,24 +88,24 @@ over the specified Terraform modules. Types: - testTerraform: - - modules (`attrsOf moduleType`): Optional. - Path to Terraform modules to lint. - Defaults to `{ }`. + - modules (`attrsOf moduleType`): Optional. + Path to Terraform modules to lint. + Defaults to `{ }`. - moduleType (`submodule`): - - setup (`listOf package`): Optional. - [Makes Environment](./environment.md) - or [Makes Secrets](./secrets.md) - to `source` (as in Bash's `source`) - before anything else. - Defaults to `[ ]`. - - src (`str`): - Path to the Terraform module. - - version (`enum [ "0.14" "0.15" "1.0" ]`): - Terraform version your module is built with. - - debug (`bool`): Optional. - Enable maximum level of debugging - and remove parallelism so logs are clean. - Defaults to `false`. + - setup (`listOf package`): Optional. + [Makes Environment](./environment.md) + or [Makes Secrets](./secrets.md) + to `source` (as in Bash's `source`) + before anything else. + Defaults to `[ ]`. + - src (`str`): + Path to the Terraform module. + - version (`enum [ "0.14" "0.15" "1.0" ]`): + Terraform version your module is built with. + - debug (`bool`): Optional. + Enable maximum level of debugging + and remove parallelism so logs are clean. + Defaults to `false`. Example: diff --git a/docs/src/api/builtins/utilities.md b/docs/src/api/builtins/utilities.md index fc609dc48..63c20954a 100644 --- a/docs/src/api/builtins/utilities.md +++ b/docs/src/api/builtins/utilities.md @@ -4,8 +4,8 @@ without having to specify them on any file. ## makeNodeJsLock -You can generate a `package-lock.json` -for [makeNodeJsEnvironment](#makenodejsenvironment) +You can generate a `package-lock.json` for +[makeNodeJsEnvironment](/api/extensions/node.js/#makenodejsenvironment) like this: ```bash @@ -17,15 +17,15 @@ m github:fluidattacks/makes@23.04 /utils/makeNodeJsLock \ - Supported `node_js_version`s are: `14`, `16` and `18`. - `package_json` is the **absolute path** to the `package.json` file in your - project. + project. - `package_lock` is the **absolute path** - to the `package-lock.json` file in your project, this file can be an empty - file. + to the `package-lock.json` file in your project, this file can be an empty + file. ## makePythonLock -You can generate a `sourcesYaml` -for [makePythonPypiEnvironment](#makepythonpypienvironment) +You can generate a `sourcesYaml` for +[makePythonPypiEnvironment](/api/extensions/python/#makepythonpypienvironment) like this: ```bash @@ -37,21 +37,21 @@ m github:fluidattacks/makes@23.04 /utils/makePythonLock \ - Supported `python_version`s are: `3.8`, `3.9`, `3.10` and `3.11`. - `dependencies_yaml` is the **absolute path** to a YAML file - mapping [PyPI](https://pypi.org/) packages to version constraints. - Example: + mapping [PyPI](https://pypi.org/) packages to version constraints. + Example: - ```yaml - Django: "3.2.*" - psycopg2: "2.9.1" - ``` + ```yaml + Django: "3.2.*" + psycopg2: "2.9.1" + ``` - `sources_yaml` is the **absolute path** - to a file were the script will output results. + to a file were the script will output results. ## makeRubyLock -You can generate a `sourcesYaml` -for [makeRubyGemsEnvironment](#makerubygemsenvironment) +You can generate a `sourcesYaml` for +[makeRubyGemsEnvironment](/api/extensions/ruby/#makerubygemsenvironment) like this: ```bash @@ -63,16 +63,16 @@ m github:fluidattacks/makes@23.04 /utils/makeRubyLock \ - Supported `ruby_version`s are: `2.7`, `3.0` and `3.1`. - `dependencies_yaml` is the **absolute path** to a YAML file - mapping [RubyGems](https://rubygems.org/) gems to version constraints. - Example: + mapping [RubyGems](https://rubygems.org/) gems to version constraints. + Example: - ```yaml - rubocop: "1.43.0" - slim: "~> 4.1" - ``` + ```yaml + rubocop: "1.43.0" + slim: "~> 4.1" + ``` - `sources_yaml` is the **absolute path** - to a file were the script will output results. + to a file were the script will output results. ## makeSopsEncryptedFile @@ -95,25 +95,25 @@ specified via environment variable. Types: - workspaceForTerraformFromEnv: - - modules (`attrsOf moduleType`): Optional. - Terraform modules to switch workspace. - Defaults to `{ }`. + - modules (`attrsOf moduleType`): Optional. + Terraform modules to switch workspace. + Defaults to `{ }`. - moduleType (`submodule`): - - setup (`listOf package`): Optional. - [Makes Environment](./environment.md) - or [Makes Secrets](./secrets.md) - to `source` (as in Bash's `source`) - before anything else. - Defaults to `[ ]`. - - src (`str`): - Path to the Terraform module. - - variable (`str`): Optional. - Name of the environment variable that contains - the name of the workspace you want to use. - Defaults to `""`. - When `""` provided, workspace is `default`. - - version (`enum [ "0.14" "0.15" "1.0" ]`): - Terraform version your module is built with. + - setup (`listOf package`): Optional. + [Makes Environment](./environment.md) + or [Makes Secrets](./secrets.md) + to `source` (as in Bash's `source`) + before anything else. + Defaults to `[ ]`. + - src (`str`): + Path to the Terraform module. + - variable (`str`): Optional. + Name of the environment variable that contains + the name of the workspace you want to use. + Defaults to `""`. + When `""` provided, workspace is `default`. + - version (`enum [ "0.14" "0.15" "1.0" ]`): + Terraform version your module is built with. Example: diff --git a/docs/src/api/extensions/containers.md b/docs/src/api/extensions/containers.md index fa22f421f..60ba8a01e 100644 --- a/docs/src/api/extensions/containers.md +++ b/docs/src/api/extensions/containers.md @@ -6,15 +6,15 @@ in [OCI Format](https://github.com/opencontainers/image-spec). A container image is composed of: - 0 or more layers (binary blobs). - - Each layer contains a snapshot of the root file system (`/`), - they represent portions of it. - - When the container is executed - all layers are squashed together - to compose the root - of the file system (`/`). + - Each layer contains a snapshot of the root file system (`/`), + they represent portions of it. + - When the container is executed + all layers are squashed together + to compose the root + of the file system (`/`). - A JSON manifest (metadata) - that describes important aspects of the container, - for instance its layers, environment variables, entrypoint, etc. + that describes important aspects of the container, + for instance its layers, environment variables, entrypoint, etc. Resources: @@ -23,16 +23,16 @@ Resources: Types: - makeContainerImage (`function { ... } -> package`): - - layers (`listOf package`): Optional. - Layers of the container. - Defaults to `[ ]`. - - maxLayers (`ints.positive`): Optional. - Maximum number of layers the container can have. - Defaults to `65`. - - config (`attrsOf anything`): Optional. - Configuration manifest as described in - [OCI Runtime Configuration Manifest](https://github.com/moby/moby/blob/master/image/spec/v1.2.) - Defaults to `{ }`. + - layers (`listOf package`): Optional. + Layers of the container. + Defaults to `[ ]`. + - maxLayers (`ints.positive`): Optional. + Maximum number of layers the container can have. + Defaults to `65`. + - config (`attrsOf anything`): Optional. + Configuration manifest as described in + [OCI Runtime Configuration Manifest](https://github.com/moby/moby/blob/master/image/spec/v1.2.) + Defaults to `{ }`. Example: diff --git a/docs/src/api/extensions/fetchers.md b/docs/src/api/extensions/fetchers.md index 599b0454d..713126b72 100644 --- a/docs/src/api/extensions/fetchers.md +++ b/docs/src/api/extensions/fetchers.md @@ -5,14 +5,13 @@ Fetch a file from the specified URL. Types: - fetchUrl (`function { ... } -> package`): - - - url (`str`): - URL to download. - - sha256 (`str`): - SHA256 of the expected output, - In order to get the SHA256 - you can omit this parameter and execute Makes, - Makes will tell you the correct SHA256 on failure. + - url (`str`): + URL to download. + - sha256 (`str`): + SHA256 of the expected output, + In order to get the SHA256 + you can omit this parameter and execute Makes, + Makes will tell you the correct SHA256 on failure. Example: @@ -38,19 +37,18 @@ and unpack it. Types: - fetchArchive (`function { ... } -> package`): - - - url (`str`): - URL to download. - - sha256 (`str`): - SHA256 of the expected output, - In order to get the SHA256 - you can omit this parameter and execute Makes, - Makes will tell you the correct SHA256 on failure. - - stripRoot (`bool`): Optional. - Most archives have a symbolic top-level directory - that is discarded during unpack phase. - If this is not the case you can set this flag to `false`. - Defaults to `true`. + - url (`str`): + URL to download. + - sha256 (`str`): + SHA256 of the expected output, + In order to get the SHA256 + you can omit this parameter and execute Makes, + Makes will tell you the correct SHA256 on failure. + - stripRoot (`bool`): Optional. + Most archives have a symbolic top-level directory + that is discarded during unpack phase. + If this is not the case you can set this flag to `false`. + Defaults to `true`. Example: @@ -75,18 +73,17 @@ Fetch a commit from the specified Git repository at GitHub. Types: - fetchGithub (`function { ... } -> package`): - - - owner (`str`): - Owner of the repository. - - repo (`str`): - Name of the repository. - - rev (`str`): - Commit, branch or tag to fetch. - - sha256 (`str`): - SHA256 of the expected output, - In order to get the SHA256 - you can omit this parameter and execute Makes, - Makes will tell you the correct SHA256 on failure. + - owner (`str`): + Owner of the repository. + - repo (`str`): + Name of the repository. + - rev (`str`): + Commit, branch or tag to fetch. + - sha256 (`str`): + SHA256 of the expected output, + In order to get the SHA256 + you can omit this parameter and execute Makes, + Makes will tell you the correct SHA256 on failure. Example: @@ -113,18 +110,17 @@ Fetch a commit from the specified Git repository at GitLab. Types: - fetchGitlab (`function { ... } -> package`): - - - owner (`str`): - Owner of the repository. - - repo (`str`): - Name of the repository. - - rev (`str`): - Commit, branch or tag to fetch. - - sha256 (`str`): - SHA256 of the expected output, - In order to get the SHA256 - you can omit this parameter and execute Makes, - Makes will tell you the correct SHA256 on failure. + - owner (`str`): + Owner of the repository. + - repo (`str`): + Name of the repository. + - rev (`str`): + Commit, branch or tag to fetch. + - sha256 (`str`): + SHA256 of the expected output, + In order to get the SHA256 + you can omit this parameter and execute Makes, + Makes will tell you the correct SHA256 on failure. Example: @@ -157,22 +153,22 @@ Fetch a commit from the Types: - fetchNixpkgs (`function { ... } -> anything`): - - rev (`str`): - Commit, branch or tag to fetch. - - allowUnfree (`bool`): Optional. - Allow software that do not respect the freedom of its users. - Defaults to `true`. - - acceptAndroidSdkLicense (`bool`): Optional. - Accept the Android SDK license. - Defaults to `true`. - - overalys (`listOf overlayType`): Optional. - Overlays to apply to the Nixpkgs set. - Defaults to `[ ]`. - - sha256 (`str`): - SHA256 of the expected output, - In order to get the SHA256 - you can omit this parameter and execute Makes, - Makes will tell you the correct SHA256 on failure. + - rev (`str`): + Commit, branch or tag to fetch. + - allowUnfree (`bool`): Optional. + Allow software that do not respect the freedom of its users. + Defaults to `true`. + - acceptAndroidSdkLicense (`bool`): Optional. + Accept the Android SDK license. + Defaults to `true`. + - overalys (`listOf overlayType`): Optional. + Overlays to apply to the Nixpkgs set. + Defaults to `[ ]`. + - sha256 (`str`): + SHA256 of the expected output, + In order to get the SHA256 + you can omit this parameter and execute Makes, + Makes will tell you the correct SHA256 on failure. Example: @@ -200,13 +196,13 @@ from [RubyGems](https://rubygems.org/). Types: - fetchRubyGem (`function { ... } -> package`): - - sha256 (`str`): - SHA256 of the expected output, - In order to get the SHA256 - you can omit this parameter and execute Makes, - Makes will tell you the correct SHA256 on failure. - - url (`str`): - url of the gem to download. + - sha256 (`str`): + SHA256 of the expected output, + In order to get the SHA256 + you can omit this parameter and execute Makes, + Makes will tell you the correct SHA256 on failure. + - url (`str`): + url of the gem to download. Example: diff --git a/docs/src/api/extensions/format-conversion.md b/docs/src/api/extensions/format-conversion.md index f20622e34..4b25bf417 100644 --- a/docs/src/api/extensions/format-conversion.md +++ b/docs/src/api/extensions/format-conversion.md @@ -6,9 +6,8 @@ to a Nix expression. Types: - fromJson (`function str -> anything`): - - - (`str`): - JSON formatted string to convert. + - (`str`): + JSON formatted string to convert. Example: @@ -63,9 +62,8 @@ to a Nix expression. Types: - fromToml (`function str -> anything`): - - - (`str`): - TOML formatted string to convert. + - (`str`): + TOML formatted string to convert. Example: @@ -119,9 +117,8 @@ to a Nix expression. Types: - fromYaml (`function str -> anything`): - - - (`str`): - YAML formatted string to convert. + - (`str`): + YAML formatted string to convert. Example: @@ -177,10 +174,9 @@ to Bash. Types: - toBashArray (`function (listOf strLike) -> package`): - - - (`listOf strLike`): - list of arguments - to transform. + - (`listOf strLike`): + list of arguments + to transform. Example: @@ -233,9 +229,8 @@ You can combine with toBashArray for more complex structures. Types: - toBashMap (`function (attrsOf strLike) -> package`): - - - (`attrsOf strLike`): - expression to transform. + - (`attrsOf strLike`): + expression to transform. Example: @@ -288,11 +283,10 @@ into a JSON file. Types: - toFileJson (`function str anything -> package`): - - - (`str`): - Name of the created file. - - (`anything`): - Nix expression to convert. + - (`str`): + Name of the created file. + - (`anything`): + Nix expression to convert. Example: @@ -334,9 +328,8 @@ equivalent. Types: - toFileJsonFromFileYaml (`function package -> package`): - - - (`package`): - YAML file to transform. + - (`package`): + YAML file to transform. Example: @@ -393,11 +386,10 @@ into a YAML file. Types: - toFileYaml (`function str anything -> package`): - - - (`str`): - Name of the created file. - - (`anything`): - Nix expression to convert. + - (`str`): + Name of the created file. + - (`anything`): + Nix expression to convert. Example: diff --git a/docs/src/api/extensions/fundamentals.md b/docs/src/api/extensions/fundamentals.md index 8bce13e22..e96b39318 100644 --- a/docs/src/api/extensions/fundamentals.md +++ b/docs/src/api/extensions/fundamentals.md @@ -19,9 +19,7 @@ A [Nix derivation](https://nixos.org/manual/nix/unstable/expressions/derivations is the process of: - taking zero or more inputs - - transforming them as we see fit - - placing the results in the output path Derivation outputs live in the `/nix/store`. @@ -60,38 +58,28 @@ Below we describe shortly the purpose of the environment variables we currently support. - [CLASSPATH](https://www.javatpoint.com/how-to-set-classpath-in-java): - Location of user-defined classes and packages. - + Location of user-defined classes and packages. - [CRYSTAL_LIBRARY_PATH](https://crystal-lang.org/reference/guides/static_linking.html): - Location of Crystal libraries. - + Location of Crystal libraries. - [GEM_PATH](https://guides.rubygems.org/command-reference): - Location of libraries for Ruby. - + Location of libraries for Ruby. - [LD_LIBRARY_PATH](https://linuxhint.com/what-is-ld-library-path/): - Location of libraries for Dynamic Linking Loaders. - + Location of libraries for Dynamic Linking Loaders. - [MYPYPATH](https://mypy.readthedocs.io/en/stable/running_mypy.html): - Location of library stubs and static types - for [MyPy](https://mypy.readthedocs.io/en/stable/). - + Location of library stubs and static types + for [MyPy](https://mypy.readthedocs.io/en/stable/). - [NODE_PATH](https://nodejs.org/api/modules.html): - Location of Node.js modules. - + Location of Node.js modules. - [OCAMLPATH](https://github.com/ocaml/ocaml/issues/8898): - Location of OCaml libraries. - + Location of OCaml libraries. - [CAML_LD_LIBRARY_PATH](https://ocaml.org/manual/runtime.html): - Location of OCaml stublibs. - + Location of OCaml stublibs. - [PATH](https://opensource.com/article/17/6/set-path-linux): - Location of directories where executable programs are located. - + Location of directories where executable programs are located. - [PKG_CONFIG_PATH](https://linux.die.net/man/1/pkg-config): - Location of pkg-config packages. - + Location of pkg-config packages. - [PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH): - Location of Python modules and site-packages. + Location of Python modules and site-packages. `makeSearchPaths` helps you write code like this: @@ -110,194 +98,170 @@ export PATH="/nix/store/m5kp2jhiga25ynk3iq61f4psaqixg7ib-git-2.32.0/bin${PATH:+: Types: - makeSearchPaths (`function { ... } -> package`): - - - `bin` (`listOf coercibleToStr`): Optional. - Append `/bin` - of each element in the list - to PATH. - Defaults to `[ ]`. - - - `rpath` (`listOf coercibleToStr`): Optional. - Append `/lib` and `/lib64` - of each element in the list - to LD_LIBRARY_PATH. - Defaults to `[ ]`. - - - `source` (`listOf coercibleToStr`): Optional. - Source (as in Bash's `source` command) - each element in the list. - Defaults to `[ ]`. + - `bin` (`listOf coercibleToStr`): Optional. + Append `/bin` + of each element in the list + to PATH. + Defaults to `[ ]`. + - `rpath` (`listOf coercibleToStr`): Optional. + Append `/lib` and `/lib64` + of each element in the list + to LD_LIBRARY_PATH. + Defaults to `[ ]`. + - `source` (`listOf coercibleToStr`): Optional. + Source (as in Bash's `source` command) + each element in the list. + Defaults to `[ ]`. Types specific to Crystal: - makeSearchPaths (`function { ... } -> package`): - - - `crystalLib` (`listOf coercibleToStr`): Optional. - Append `/lib` - of each element in the list - to CRYSTAL_LIBRARY_PATH. - Defaults to `[ ]`. + - `crystalLib` (`listOf coercibleToStr`): Optional. + Append `/lib` + of each element in the list + to CRYSTAL_LIBRARY_PATH. + Defaults to `[ ]`. Types specific to Java: - makeSearchPaths (`function { ... } -> package`): - - - `javaClass` (`listOf coercibleToStr`): Optional. - Append each element in the list - to CLASSPATH. - Defaults to `[ ]`. + - `javaClass` (`listOf coercibleToStr`): Optional. + Append each element in the list + to CLASSPATH. + Defaults to `[ ]`. Types specific to Kubernetes: - makeSearchPaths (`function { ... } -> package`): - - - `kubeConfig` (`listOf coercibleToStr`): Optional. - Append each element in the list - to [KUBECONFIG](https://kubernetes.io/docs/concepts/configuration/). - Defaults to `[ ]`. + - `kubeConfig` (`listOf coercibleToStr`): Optional. + Append each element in the list + to [KUBECONFIG](https://kubernetes.io/docs/concepts/configuration/). + Defaults to `[ ]`. Types specific to pkg-config: - makeSearchPaths (`function { ... } -> package`): - - - `pkgConfig` (`listOf coercibleToStr`): Optional. - Append `/lib/pkgconfig` - of each element in the list - to PKG_CONFIG_PATH. - Defaults to `[ ]`. + - `pkgConfig` (`listOf coercibleToStr`): Optional. + Append `/lib/pkgconfig` + of each element in the list + to PKG_CONFIG_PATH. + Defaults to `[ ]`. Types specific to OCaml: - makeSearchPaths (`function { ... } -> package`): - - - `ocamlBin` (`listOf coercibleToStr`): Optional. - Append `/bin` - of each element in the list - to PATH. - Defaults to `[ ]`. - - - `ocamlLib` (`listOf coercibleToStr`): Optional. - Append `/` - of each element in the list - to OCAMLPATH. - Defaults to `[ ]`. - - - `ocamlStublib` (`listOf coercibleToStr`): Optional. - Append `/stublib` - of each element in the list - to CAML_LD_LIBRARY_PATH. - Defaults to `[ ]` + - `ocamlBin` (`listOf coercibleToStr`): Optional. + Append `/bin` + of each element in the list + to PATH. + Defaults to `[ ]`. + - `ocamlLib` (`listOf coercibleToStr`): Optional. + Append `/` + of each element in the list + to OCAMLPATH. + Defaults to `[ ]`. + - `ocamlStublib` (`listOf coercibleToStr`): Optional. + Append `/stublib` + of each element in the list + to CAML_LD_LIBRARY_PATH. + Defaults to `[ ]` Types specific to Python: - makeSearchPaths (`function { ... } -> package`): - - - `pythonMypy` (`listOf coercibleToStr`): Optional. - Append `/` - of each element in the list - to MYPYPATH. - Defaults to `[ ]`. - - - `pythonMypy38` (`listOf coercibleToStr`): Optional. - Append `/lib/python3.8/site-packages` - of each element in the list - to MYPYPATH. - Defaults to `[ ]`. - - - `pythonMypy39` (`listOf coercibleToStr`): Optional. - Append `/lib/python3.9/site-packages` - of each element in the list - to MYPYPATH. - Defaults to `[ ]`. - - - `pythonMypy310` (`listOf coercibleToStr`): Optional. - Append `/lib/python3.10/site-packages` - of each element in the list - to MYPYPATH. - Defaults to `[ ]`. - - - `pythonMypy311` (`listOf coercibleToStr`): Optional. - Append `/lib/python3.11/site-packages` - of each element in the list - to MYPYPATH. - Defaults to `[ ]`. - - - `pythonPackage` (`listOf coercibleToStr`): Optional. - Append `/` - of each element in the list - to PYTHONPATH. - Defaults to `[ ]`. - - - `pythonPackage38` (`listOf coercibleToStr`): Optional. - Append `/lib/python3.8/site-packages` - of each element in the list - to PYTHONPATH. - Defaults to `[ ]`. - - - `pythonPackage39` (`listOf coercibleToStr`): Optional. - Append `/lib/python3.9/site-packages` - of each element in the list - to PYTHONPATH. - Defaults to `[ ]`. - - - `pythonPackage310` (`listOf coercibleToStr`): Optional. - Append `/lib/python3.10/site-packages` - of each element in the list - to PYTHONPATH. - Defaults to `[ ]`. - - - `pythonPackage311` (`listOf coercibleToStr`): Optional. - Append `/lib/python3.11/site-packages` - of each element in the list - to PYTHONPATH. - Defaults to `[ ]`. + - `pythonMypy` (`listOf coercibleToStr`): Optional. + Append `/` + of each element in the list + to MYPYPATH. + Defaults to `[ ]`. + - `pythonMypy38` (`listOf coercibleToStr`): Optional. + Append `/lib/python3.8/site-packages` + of each element in the list + to MYPYPATH. + Defaults to `[ ]`. + - `pythonMypy39` (`listOf coercibleToStr`): Optional. + Append `/lib/python3.9/site-packages` + of each element in the list + to MYPYPATH. + Defaults to `[ ]`. + - `pythonMypy310` (`listOf coercibleToStr`): Optional. + Append `/lib/python3.10/site-packages` + of each element in the list + to MYPYPATH. + Defaults to `[ ]`. + - `pythonMypy311` (`listOf coercibleToStr`): Optional. + Append `/lib/python3.11/site-packages` + of each element in the list + to MYPYPATH. + Defaults to `[ ]`. + - `pythonPackage` (`listOf coercibleToStr`): Optional. + Append `/` + of each element in the list + to PYTHONPATH. + Defaults to `[ ]`. + - `pythonPackage38` (`listOf coercibleToStr`): Optional. + Append `/lib/python3.8/site-packages` + of each element in the list + to PYTHONPATH. + Defaults to `[ ]`. + - `pythonPackage39` (`listOf coercibleToStr`): Optional. + Append `/lib/python3.9/site-packages` + of each element in the list + to PYTHONPATH. + Defaults to `[ ]`. + - `pythonPackage310` (`listOf coercibleToStr`): Optional. + Append `/lib/python3.10/site-packages` + of each element in the list + to PYTHONPATH. + Defaults to `[ ]`. + - `pythonPackage311` (`listOf coercibleToStr`): Optional. + Append `/lib/python3.11/site-packages` + of each element in the list + to PYTHONPATH. + Defaults to `[ ]`. Types specific to Node.js: - makeSearchPaths (`function { ... } -> package`): - - - `nodeBin` (`listOf coercibleToStr`): Optional. - Append `/.bin` - of each element in the list - to PATH. - Defaults to `[ ]`. - - - `nodeModule` (`listOf coercibleToStr`): Optional. - Append `/` - of each element in the list - to NODE_PATH. - Defaults to `[ ]`. + - `nodeBin` (`listOf coercibleToStr`): Optional. + Append `/.bin` + of each element in the list + to PATH. + Defaults to `[ ]`. + - `nodeModule` (`listOf coercibleToStr`): Optional. + Append `/` + of each element in the list + to NODE_PATH. + Defaults to `[ ]`. Types specific to Ruby: - makeSearchPaths (`function { ... } -> package`): - - - `rubyBin` (`listOf coercibleToStr`): Optional. - Append `/bin` - of each element in the list - to PATH. - Defaults to `[ ]`. - - - `rubyGemPath` (`listOf coercibleToStr`): Optional. - Append `/` - of each element in the list - to GEM_PATH. - Defaults to `[ ]`. + - `rubyBin` (`listOf coercibleToStr`): Optional. + Append `/bin` + of each element in the list + to PATH. + Defaults to `[ ]`. + - `rubyGemPath` (`listOf coercibleToStr`): Optional. + Append `/` + of each element in the list + to GEM_PATH. + Defaults to `[ ]`. Types for non covered cases: - makeSearchPaths (`function { ... } -> package`): + - `export` (`listOf (tuple [ str coercibleToStr str ])`): Optional. + Export (as in Bash's `export` command) + each tuple in the list. - - `export` (`listOf (tuple [ str coercibleToStr str ])`): Optional. - Export (as in Bash's `export` command) - each tuple in the list. - Defaults to `[ ]`. + Defaults to `[ ]`. - Tuples elements are: + Tuples elements are: - - Name of the environment variable to export. - - Base package to export from. - - Relative path with respect to the package that should be appended. + - Name of the environment variable to export. + - Base package to export from. + - Relative path with respect to the package that should be appended. Example: @@ -347,55 +311,54 @@ Example: Perform a build step in an **isolated** environment: - External environment variables are not visible by the builder script. - This means you **can't** use secrets here. + This means you **can't** use secrets here. - Search Paths as in `makeSearchPaths` are completely empty. - The `HOME` environment variable is set to `/homeless-shelter`. - Only [GNU coreutils][gnu_coreutils] commands (cat, echo, ls, ...) - are present by default. + are present by default. - An environment variable called `out` is present - and represents the derivation's output. - The derivation **must** produce an output, - may be a file, or a directory. + and represents the derivation's output. + The derivation **must** produce an output, + may be a file, or a directory. - Convenience bash functions are exported: - - - `echo_stderr`: Like `echo` but to standard error. - - `debug`: Like `echo_stderr` but with a `[DEBUG]` prefix. - - `info`: Like `echo_stderr` but with a `[INFO]` prefix. - - `warn`: Like `echo_stderr` but with a `[WARNING]` prefix. - - `error`: Like `echo_stderr` but with a `[ERROR]` prefix. - Returns exit code 1 to signal failure. - - `critical`: Like `echo_stderr` but with a `[CRITICAL]` prefix. - Exits immediately with exit code 1, aborting the entire execution. - - `copy`: Like `cp` but making paths writeable after copying them. - - `require_env_var`: `error`s when the specified env var is not set, - or set to an empty value. - - ```bash - require_env_var USERNAME - ``` + - `echo_stderr`: Like `echo` but to standard error. + - `debug`: Like `echo_stderr` but with a `[DEBUG]` prefix. + - `info`: Like `echo_stderr` but with a `[INFO]` prefix. + - `warn`: Like `echo_stderr` but with a `[WARNING]` prefix. + - `error`: Like `echo_stderr` but with a `[ERROR]` prefix. + Returns exit code 1 to signal failure. + - `critical`: Like `echo_stderr` but with a `[CRITICAL]` prefix. + Exits immediately with exit code 1, aborting the entire execution. + - `copy`: Like `cp` but making paths writeable after copying them. + - `require_env_var`: `error`s when the specified env var is not set, + or set to an empty value. + + ```bash + require_env_var USERNAME + ``` - After the build, for all paths in `$out`: - - User and group ownership are removed - - Last-modified timestamps are reset to `1970-01-01T00:00:00+00:00`. + - User and group ownership are removed + - Last-modified timestamps are reset to `1970-01-01T00:00:00+00:00`. Types: - makeDerivation (`function { ... } -> package`): - - builder (`either str package`): - A Bash script that performs the build step. - - env (`attrsOf str`): Optional. - Environment variables that will be propagated to the `builder`. - Variable names must start with `env`. - Defaults to `{ }`. - - local (`bool`): Optional. - Should we always build locally this step? - Thus effectively ignoring any configured binary caches. - Defaults to `false`. - - name (`str`): - Custom name to assign to the build step, be creative, it helps in debugging. - - searchPaths (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths`. - Defaults to `makeSearchPaths`'s defaults. + - builder (`either str package`): + A Bash script that performs the build step. + - env (`attrsOf str`): Optional. + Environment variables that will be propagated to the `builder`. + Variable names must start with `env`. + Defaults to `{ }`. + - local (`bool`): Optional. + Should we always build locally this step? + Thus effectively ignoring any configured binary caches. + Defaults to `false`. + - name (`str`): + Custom name to assign to the build step, be creative, it helps in debugging. + - searchPaths (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths`. + Defaults to `makeSearchPaths`'s defaults. Example: @@ -450,20 +413,20 @@ in a file of any format. Types: - makeTemplate (`function { ... } -> package`): - - local (`bool`): Optional. - Should we always build locally this step? - Thus effectively ignoring any configured binary caches. - Defaults to `true`. - - name (`str`): - Custom name to assign to the build step, be creative, it helps in debugging. - - replace (`attrsOf strLike`): Optional. - Placeholders will be replaced in the script with their respective value. - Variable names must start with `__arg`, end with `__` - and have at least 6 characters long. - Defaults to `{ }`. - - template (`either str package`): - A string, file, output or package - in which placeholders will be replaced. + - local (`bool`): Optional. + Should we always build locally this step? + Thus effectively ignoring any configured binary caches. + Defaults to `true`. + - name (`str`): + Custom name to assign to the build step, be creative, it helps in debugging. + - replace (`attrsOf strLike`): Optional. + Placeholders will be replaced in the script with their respective value. + Variable names must start with `__arg`, end with `__` + and have at least 6 characters long. + Defaults to `{ }`. + - template (`either str package`): + A string, file, output or package + in which placeholders will be replaced. Example: @@ -505,83 +468,83 @@ that runs in a **almost-isolated** environment. - The file system is **not** isolated, the script runs in user-space. - External environment variables are visible by the script. - You can use this to propagate secrets. + You can use this to propagate secrets. - Search Paths as in `makeSearchPaths` are completely empty. - The `HOME_IMPURE` environment variable is set to the user's home directory. - The `HOME` environment variable is set to a temporary directory. - Only [GNU coreutils][gnu_coreutils] commands (cat, echo, ls, ...) - are present by default. + are present by default. - An environment variable called `STATE` points to a directory - that can be used to store the script's state (if any). - That state can be optionally persisted. - That state can be optionally shared across repositories. + that can be used to store the script's state (if any). + That state can be optionally persisted. + That state can be optionally shared across repositories. - Convenience bash functions are exported: - - - `running_in_ci_cd_provider`: - Detects if we are running on the CI/CD provider (gitlab/github/etc). - - ```bash - if running_in_ci_cd_provider; then - # ci/cd logic - else - # non ci/cd logic - fi - ``` - - - `prompt_user_for_confirmation`: - Warns the user about a possibly destructive action - that will be executed soon - and aborts if the user does not confirm aproppriately. - - This function assumes a positive answer - when running on the CI/CD provider - because there is no human interaction. - - - `prompt_user_for_input`: - Ask the user to type information - or optionally use a default value by pressing ENTER. - - This function assumes the default value - when running on the CI/CD provider - because there is no human interaction. - - ```bash - user_supplied_input="$(prompt_user_for_input "default123123")" - - info Supplied input: "${user_supplied_input}" - ``` + - `running_in_ci_cd_provider`: + Detects if we are running on the CI/CD provider (gitlab/github/etc). + + ```bash + if running_in_ci_cd_provider; then + # ci/cd logic + else + # non ci/cd logic + fi + ``` + + - `prompt_user_for_confirmation`: + Warns the user about a possibly destructive action + that will be executed soon + and aborts if the user does not confirm aproppriately. + + This function assumes a positive answer + when running on the CI/CD provider + because there is no human interaction. + - `prompt_user_for_input`: + Ask the user to type information + or optionally use a default value by pressing ENTER. + + This function assumes the default value + when running on the CI/CD provider + because there is no human interaction. + + ```bash + user_supplied_input="$(prompt_user_for_input "default123123")" + + info Supplied input: "${user_supplied_input}" + ``` - After the build, the script is executed. Types: - makeScript (`function { ... } -> package`): - - entrypoint (`either str package`): - A Bash script that performs the build step. - - name (`str`): - Custom name to assign to the build step, be creative, it helps in debugging. - - replace (`attrsOf strLike`): Optional. - Placeholders will be replaced in the script with their respective value. - Variable names must start with `__arg`, end with `__` - and have at least 6 characters long. - Defaults to `{ }`. - - searchPaths (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths`. - Defaults to `makeSearchPaths`'s defaults. - - persistState (`bool`): Optional. - If true, state will _not_ be cleared before each script run. - Defaults to `false`. - - globalState (`bool`): Optional. - If true, script state will be written to `globalStateDir` and - to `projectStateDir` otherwise. - Defaults to `false`, if `projectStateDir` is specified or derived. - Note: - - It is implicitly `true`, if `projectStateDir == globalStateDir`. - - `projectStateDir == globalStateDir` is the default if - `projectIdentifier` is not configured. - - Hence, generally enable project local state by - - either setting `projectIdentifier` - - or `projectStateDir` different from `globalStateDir`. + - entrypoint (`either str package`): + A Bash script that performs the build step. + - name (`str`): + Custom name to assign to the build step, be creative, it helps in debugging. + - replace (`attrsOf strLike`): Optional. + Placeholders will be replaced in the script with their respective value. + Variable names must start with `__arg`, end with `__` + and have at least 6 characters long. + Defaults to `{ }`. + - searchPaths (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths`. + Defaults to `makeSearchPaths`'s defaults. + - persistState (`bool`): Optional. + If true, state will _not_ be cleared before each script run. + Defaults to `false`. + - globalState (`bool`): Optional. + If true, script state will be written to `globalStateDir` and + to `projectStateDir` otherwise. + Defaults to `false`, if `projectStateDir` is specified or derived. + + Note: + + - It is implicitly `true`, if `projectStateDir == globalStateDir`. + - `projectStateDir == globalStateDir` is the default if + `projectIdentifier` is not configured. + - Hence, generally enable project local state by + - either setting `projectIdentifier` + - or `projectStateDir` different from `globalStateDir`. Example: @@ -638,9 +601,8 @@ in the **most** pure and reproducible way possible. Types: - projectPath (`function str -> package`): - - - (`str`): - Absolute path, assumming the repository is located at `"/"`. + - (`str`): + Absolute path, assumming the repository is located at `"/"`. Example: diff --git a/docs/src/api/extensions/git.md b/docs/src/api/extensions/git.md deleted file mode 100644 index cec22c5f6..000000000 --- a/docs/src/api/extensions/git.md +++ /dev/null @@ -1,76 +0,0 @@ -## libGit - -A small template for doing git kung-fu. - -Types: - -- libGit (`package`): - A package that can be sourced to setup functions in the current scope. - The list of available functions is documented below: - - - `is_git_repository`: - Return 0 if the provided path is a git repository. - - ```bash - if is_git_repository /path/to/anywhere; then - # custom logic - fi - ``` - - - `require_git_repository`: - Stops the execution - if the provided path is not a git repository. - - ```bash - require_git_repository /path/to/anywhere - ``` - - - `get_abbrev_rev`: - If available, returns an abbreviated name for the provided revision. - Otherwise returns the revision unchanged. - - ```bash - # Would return main, trunk, develop, etc - get_abbrev_rev /path/to/anywhere HEAD - ``` - - - `get_commit_from_rev`: - If available, returns the full commit of the provided revision. - Otherwise returns an error. - - ```bash - # Would return the full commit (e026a413...) - get_commit_from_rev /path/to/anywhere HEAD - ``` - -Example: - -=== "main.nix" - - ```nix - # /path/to/my/project/makes/example/main.nix - { - libGit, - makeScript, - ... - }: - makeScript { - entrypoint = '' - require_git_repository /some-path-that-do-not-exists - - echo other business logic goes here ... - ''; - name = "example"; - searchPaths = { - source = [ libGit ]; - }; - } - ``` - -=== "Invocation" - - ```bash - $ m . /example - - [CRITICAL] We require a git repository, but this one is not: /some-path-that-do-not-exists - ``` diff --git a/docs/src/api/extensions/index.md b/docs/src/api/extensions/index.md index c46fe5f4d..b69c30edb 100644 --- a/docs/src/api/extensions/index.md +++ b/docs/src/api/extensions/index.md @@ -36,16 +36,16 @@ Now run makes! - List all available outputs: `$ m .` - ``` - Outputs list for project: /path/to/my/project - /example - ``` + ``` + Outputs list for project: /path/to/my/project + /example + ``` - Build and run the output: `$ m . /example` - ``` - Hello from Makes! - ``` + ``` + Hello from Makes! + ``` Makes will automatically recognize as outputs all `main.nix` files under the `makes/` directory in the root of the project. diff --git a/docs/src/api/extensions/node.js.md b/docs/src/api/extensions/node.js.md index dafeb17f8..e84d8820a 100644 --- a/docs/src/api/extensions/node.js.md +++ b/docs/src/api/extensions/node.js.md @@ -5,9 +5,8 @@ Get a specific Node.js version interpreter. Types: - makeNodeJsVersion (`function str -> package`): - - - (`enum [ "14" "16" "18" ]`): - Node.js version to use. + - (`enum [ "14" "16" "18" ]`): + Node.js version to use. Example: @@ -47,21 +46,20 @@ for the given Node.js project. Types: - makeNodeJsModules (`function { ... } -> package`): - - - name (`str`): - Custom name to assign to the build step, be creative, it helps in debugging. - - nodeJsVersion (`enum [ "14" "16" "18" ]`): - Node.js version to use. - - packageJson (`package`): - Path to the `package.json` of your project. - - packageLockJson (`package`): - Path to the `package-lock.json` of your project. - - searchPaths (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths`. - Defaults to `makeSearchPaths`'s defaults. - - shouldIgnoreScripts (`bool`): Optional. - Enable to propagate the `--ignore-scripts true` flag to npm. - Defaults to `false`. + - name (`str`): + Custom name to assign to the build step, be creative, it helps in debugging. + - nodeJsVersion (`enum [ "14" "16" "18" ]`): + Node.js version to use. + - packageJson (`package`): + Path to the `package.json` of your project. + - packageLockJson (`package`): + Path to the `package-lock.json` of your project. + - searchPaths (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths`. + Defaults to `makeSearchPaths`'s defaults. + - shouldIgnoreScripts (`bool`): Optional. + Enable to propagate the `--ignore-scripts true` flag to npm. + Defaults to `false`. Example: @@ -142,26 +140,26 @@ It appends: - `node_modules/.bin` to `PATH`. - `node_modules` to [NODE_PATH](https://nodejs.org/api/modules.html). -Pre-requisites: [Generating a package-lock.json](#makenodejslock) +Pre-requisites: +[Generating a package-lock.json](/api/builtins/utilities#makenodejslock) Types: - makeNodeJsEnvironment (`function { ... } -> package`): - - - name (`str`): - Custom name to assign to the build step, be creative, it helps in debugging. - - nodeJsVersion (`enum [ "14" "16" "18" ]`): - Node.js version to use. - - packageJson (`package`): - Path to the `package.json` of your project. - - packageLockJson (`package`): - Path to the `package-lock.json` of your project. - - searchPaths (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths`. - Defaults to `makeSearchPaths`'s defaults. - - shouldIgnoreScripts (`bool`): Optional. - Enable to propagate the `--ignore-scripts true` flag to npm. - Defaults to `false`. + - name (`str`): + Custom name to assign to the build step, be creative, it helps in debugging. + - nodeJsVersion (`enum [ "14" "16" "18" ]`): + Node.js version to use. + - packageJson (`package`): + Path to the `package.json` of your project. + - packageLockJson (`package`): + Path to the `package-lock.json` of your project. + - searchPaths (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths`. + Defaults to `makeSearchPaths`'s defaults. + - shouldIgnoreScripts (`bool`): Optional. + Enable to propagate the `--ignore-scripts true` flag to npm. + Defaults to `false`. Example: diff --git a/docs/src/api/extensions/others.md b/docs/src/api/extensions/others.md index 05534e80e..2e2495350 100644 --- a/docs/src/api/extensions/others.md +++ b/docs/src/api/extensions/others.md @@ -1,3 +1,47 @@ +## calculateCvss3 + +Calculate [CVSS3](https://www.first.org/cvss/v3.0/specification-document) +score and severity for a +[CVSS3 Vector String](https://www.first.org/cvss/v3.0/specification-document#Vector-String). + +Types: + +- calculateCvss3 (`function str -> package`): + - (`str`): + CVSS3 Vector String + to calculate. + +Example: + +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + makeScript, + calculateCvss3, + ... + }: + makeScript { + replace = { + __argCalculate__ = calculateCvss3 + "CVSS:3.0/S:C/C:H/I:H/A:N/AV:P/AC:H/PR:H/UI:R/E:H/RL:O/RC:R/CR:H/IR:X/AR:X/MAC:H/MPR:X/MUI:X/MC:L/MA:X"; + }; + entrypoint = '' + cat "__argCalculate__" + ''; + name = "example"; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + {"score": {"base": 6.5, "temporal": 6.0, "environmental": 5.3}, "severity": {"base": "Medium", "temporal": "Medium", "environmental": "Medium"}} + ``` + ## chunks Split a given list into N chunks @@ -6,11 +50,10 @@ for workload distributed parallelization. Types: - chunks (`function list, ints.positive -> listOf (listOf Any)`): - - - (`list`): - List to split into chunks. - - (`ints.positive`): - Number of chunks to create from list. + - (`list`): + List to split into chunks. + - (`ints.positive`): + Number of chunks to create from list. Example: @@ -42,19 +85,49 @@ Example: } ``` -## calculateCvss3 +## libGit -Calculate [CVSS3](https://www.first.org/cvss/v3.0/specification-document) -score and severity for a -[CVSS3 Vector String](https://www.first.org/cvss/v3.0/specification-document#Vector-String). +A small template for doing git kung-fu. Types: -- calculateCvss3 (`function str -> package`): +- libGit (`package`): + A package that can be sourced to setup functions in the current scope. + The list of available functions is documented below: + - `is_git_repository`: + Return 0 if the provided path is a git repository. + + ```bash + if is_git_repository /path/to/anywhere; then + # custom logic + fi + ``` + + - `require_git_repository`: + Stops the execution + if the provided path is not a git repository. + + ```bash + require_git_repository /path/to/anywhere + ``` - - (`str`): - CVSS3 Vector String - to calculate. + - `get_abbrev_rev`: + If available, returns an abbreviated name for the provided revision. + Otherwise returns the revision unchanged. + + ```bash + # Would return main, trunk, develop, etc + get_abbrev_rev /path/to/anywhere HEAD + ``` + + - `get_commit_from_rev`: + If available, returns the full commit of the provided revision. + Otherwise returns an error. + + ```bash + # Would return the full commit (e026a413...) + get_commit_from_rev /path/to/anywhere HEAD + ``` Example: @@ -63,19 +136,20 @@ Example: ```nix # /path/to/my/project/makes/example/main.nix { + libGit, makeScript, - calculateCvss3, ... }: makeScript { - replace = { - __argCalculate__ = calculateCvss3 - "CVSS:3.0/S:C/C:H/I:H/A:N/AV:P/AC:H/PR:H/UI:R/E:H/RL:O/RC:R/CR:H/IR:X/AR:X/MAC:H/MPR:X/MUI:X/MC:L/MA:X"; - }; entrypoint = '' - cat "__argCalculate__" + require_git_repository /some-path-that-do-not-exists + + echo other business logic goes here ... ''; name = "example"; + searchPaths = { + source = [ libGit ]; + }; } ``` @@ -84,7 +158,7 @@ Example: ```bash $ m . /example - {"score": {"base": 6.5, "temporal": 6.0, "environmental": 5.3}, "severity": {"base": "Medium", "temporal": "Medium", "environmental": "Medium"}} + [CRITICAL] We require a git repository, but this one is not: /some-path-that-do-not-exists ``` ## makeSslCertificate @@ -98,20 +172,19 @@ in text form. Types: - makeSslCertificate (`function { ... } -> package`): - - - days (`ints.positive`): Optional. - Ammount of days to certify the certificate for. - Defaults to `30`. - - keyType (`str`): Optional. - Defines the key type for the certificate - (option used for the `-newkey` option on the `req` command). - It uses the form `rsa:nbits`, where `nbits` is the number of bits. - Defaults to `rsa:4096`. - - name (`str`): - Custom name to assign to the build step, be creative, it helps in debugging. - - options (`listOf (listOf str)`): - Contains a list of options to create the certificate with your own needs. - Here you can use the same options used with `openssl req`. + - days (`ints.positive`): Optional. + Ammount of days to certify the certificate for. + Defaults to `30`. + - keyType (`str`): Optional. + Defines the key type for the certificate + (option used for the `-newkey` option on the `req` command). + It uses the form `rsa:nbits`, where `nbits` is the number of bits. + Defaults to `rsa:4096`. + - name (`str`): + Custom name to assign to the build step, be creative, it helps in debugging. + - options (`listOf (listOf str)`): + Contains a list of options to create the certificate with your own needs. + Here you can use the same options used with `openssl req`. Example: @@ -149,59 +222,78 @@ Example: $ m . /example -----BEGIN PRIVATE KEY----- - MIIJQwIBADANBgkqhkiG9w0BAQEFAASCCS0wggkpAgEAAoICAQDQ/tFdIW3kL1IJ - hjD11ZTTDvMXlO+Zm3Oc3Z67Kb9llNpdgyDXBXyFriAfDsDAw/Hrp7zSqzNMT5Qh - fc1OFhM2ICuPaFCQONKsOulo3LhdjXfSDuvu1k0XMF0cDOVwhQkxYdsE9/jZQUSi - CB4I2A8LLnkMvZ+ANJIFzjkxey2A+v3KMeE5aw2PLqj8H+jAuxM56fCgFrXhhmPh - U6HNlhf+dvaV/PHjpr66HJf8gF/DwhzQ+ppYbVsBnuvzmiTz/dix9wu7m3/RxVIM - OwEPcZU2VCXT2MCtXKd6H+h8vEdx1xrLYRTWUhrOnNgNrblXhlpo0frI6XloujR3 - o5x18/GjCht6gx3D/ze+g6bhgGVUxMIMuM5uCLyOxCG/M23WaAZVOgseqnggCVP7 - MA/c7sd+cIWfS5Yi04G0vXkiQDUMOhRIZM2CFKr6Lyi6hdU2bUkx9gWSQWPMcwko - kFRkv1UpzWMfD8nMphuWwMJZckNDrmUb4kK8bfum/Q+9/EYNREEpDxz6OUNezjbq - g5r8lFNcfmAySZXFGSZdANS+u1CpcyWzMtgUIvjtANeqjJw+zOMqQBBeSROpgusY - z9N8G3ZPkArIKTpKRpPdwfIPCALd5ZLrdZAJMuPTHBFGRn/oxWg/zHNYBkLTiPAJ - R9V8mz4Q59WFoF92vNmPVp1bcBtqjQIDAQABAoICAETZjXNWzfL8O9RzZrG1+N9G - 74J3SC+cbIvi3qXd7PW0AfQIfMsZPZp0cJSKsalPY+U0Txo/2BhtpukZnob48r9D - /dWykcfRUGX4ymgHPp1jO3PyAnueEatv/Vx+Sx+0VAD2scaDQnGf9NJERlC3jM0s - NCikV2VO7EQJWgIZCDaTeQQhRoc54y+mOXlFsdG8T2smzGSQ1r5DHahfetBVf/YO - jtF+kNlkVzTMsq02RVYiHogh5rL246I3Dpgj0cSnfbmzHyRg58zdalgpIAJMctGB - Cy0tHNx/x5SN6nMdO5QfPu59PvYT+kzSksJ+1q4kzqf1dN63O43qudooBiU9hf6N - RrocVXwr/vXyo78gOKN706guxf5VP3+4ldeV5AP2tCSEsI0D2H/Mbt3PlLce6zxc - BMb6lpM6XddMXkqU993ewhMqRMvvSuqNXuHp6dYmt76v0yL3GwaB3rqt1BtwPwOx - TNmoP4wcoAjKL1Q66cIFW9oZT+XuxZFn57Ch6hrxNLKzEOgtbGtuCNuCQoDVBWX5 - CLj2Oh+rK9v0Zmz4NNNDsmY3m3ViMQz4i52PuChtm3E/2dR1GsoQsy8Js3IWC9g+ - Kr7cGyL3KcOVc7snx6d6CRqKaZTsiDOX5GlQbHb3KKUAVJlGB37rXITy/yFnPffz - Rv91dVb/RFucmagBDUABAoIBAQD5A3+sHjQYgQI10ceiqEDqzqyjAog4Jg91Qt8M - qII8fUZC2yUF2kyHYeokEr4LXiYSS5GvNJ0Fm8BF4/ShuRECkU+tG73Y8JMChjfD - CU89d0G4X2I6AZShOAaWd4ypW5CsoVC7fa5Jzbd/C8RucXDJlZQlpl0Dr4VEs53Y - +a6uSmw4EPMTTrCLH2bqWXLuW3reaZM38QrbLhk5kZRTYvo2YOdmfscFop4TbEJF - qpOA0E2N5iWUnU4K6fVcBKIycsz2Ao9D1Jk1NzZGxvcvc0YxjoBSyqLZOZ9Z3Wh7 - YkfyUs4TuaEHP6/JxGBWTs7jmKdigeFfsNYRS8BFdSs3jsgBAoIBAQDW2+TkJBm2 - oXbTIuNSoYxdJocdScktLAfVH+YzrSQ78dbSs5hcVwS0WugD30Fr1n0cZ7EttbZE - FF5ZxzqHVV0mrMH64OiuhVTW6bXzlJ+V6bs4Sq/fL/iiEIoNm5D2GNrWbcYEIJ8h - Fj6QOyp8VnkAfLmYTb5ohlNQVZLr8IMpeTF4vQUCkP9umtn0S+lp8ZXNy6yTNSay - mqxbZ0pju79nk+W99TapM4FNXLoHjtkqBVu4XYlS4qX8gd1plMzZdSvUW8fWjUhR - BvbW+dqxCuryBjbHkB7rl3dSFFvl8I3JPy4fiIkHln3OEe0Cpas/IrTY+xshA3kt - kMNE+3SO50KNAoIBAQDF0Wi4dBoQqVP3K1r7tcw0fNEagmVyrZG0JtaI+MjVgvOx - IuSLfLs1Baz60UTWRQnbmNr4I8Tl8rBRFWF+pEWGE6gHLjWoRJ2U8MkVkKy5eKbl - 8ChZSm4nkRlyqTA+TjZlXZWEDLjLerheHhwDXO0rxz80la/owKQPSt2Hw/poDUlh - VN21pdqL+vtICp1KC7RVQeupEjz8l+eEG0mI4OVDE8JgYzB6IpCPf346V+Lr/w7N - Plr2b+zSsL+xRSERELAQc0IasaawZtcgbOlrcZj+v2Tj4IR0KtmTi1d4RUBAmlWJ - x/rLhmWA1RdvGRY0Kk427FT9Lr8waEwrIYSekzgBAoIBACEDjLoZafIMAUwT8kYC - GKU/hEdVzRmpyFJRIngSRJ0JXe7mNaUKoehsh3YA2faN8I9qx2i0oRr43j6BRFcD - INsOdIfuAxK93flf09tnnNXWIjRWFYv/vP55+Bx7KN0HmKiWGXUM5iaZWmejD7Yn - O1R91a63U2iQK0EOxRKH1D+NJbLdqGVqjjUaih7lgyoKOvByOUQtSJLs/UrWJjII - 6TIrIYP8p7d7+IRAmT0MEAZK6Hr9tFoOBV81PSY5/Pf07xUkPSKUduYsYcVKgvXt - LYiet9AWLwoYLfdotW4xdjfUA2xI+HU4BICjdH2RoyyCUrN8cgCyne4IblitIo3K - rwkCggEBAN0xdTlbZEI/r1O3iDNJXcXJg3HUMj78pz7c32ROMS2iwsQTyj+IHui8 - 0J2FOdZ8TUlgoBfi3C1Y2NyNdyAJ3jiHnCrQz/sqTRYGds+aALfw1YZZuonUXAwc - OxCZcMowzTvx5iCcaCY9jsdrr4TYGWSf2wmzSD87EYqNKLTd4asOCILatTWMw0AR - xBHKugWHSokf9SNzirqxSNeqjjepMTA95LRiijKQAu9yhj0Zs35EUIu88KA5PZ4q - 0+URRTIuCtyjKBFC5qBhvbWzKe46hSy6OPyJFPgyo4OCC0NkesLQKcJwfTckK8Ne - mSjLja2l8YqKkXqV6P3R6wVLMvCoCao= + ... -----END PRIVATE KEY----- ``` +## pathShebangs + +Replace common [shebangs](https://bash.cyberciti.biz/guide/Shebang) +for their Nix equivalent. + +For example: + +- `#! /bin/env xxx` -> `/nix/store/..-name/bin/xxx` +- `#! /usr/bin/env xxx` -> `/nix/store/..-name/bin/xxx` +- `#! /path/to/my/xxx` -> `/nix/store/..-name/bin/xxx` + +Types: + +- pathShebangs (`package`): + When sourced, + it exports a Bash function called `patch_shebangs` + into the evaluation context. + This function receives one or more files or directories as arguments + and replace shebangs of the executable files in-place. + Note that only shebangs that resolve to executables in the `"${PATH}"` + (a.k.a. `searchPaths.bin`) will be taken into account. + +Example: + +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + __nixpkgs__, + makeDerivation, + patchShebangs, + ... + }: + makeDerivation { + env = { + envFile = builtins.toFile "my_file.sh" '' + #! /usr/bin/env bash + + echo Hello! + ''; + }; + builder = '' + copy $envFile $out + + chmod +x $out + patch_shebangs $out + + cat $out + ''; + name = "example"; + searchPaths = { + bin = [ __nixpkgs__.bash ]; # Propagate bash so `patch_shebangs` "sees" it + source = [ patchShebangs ]; + }; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + #! /nix/store/dpjnjrqbgbm8a5wvi1hya01vd8wyvsq4-bash-4.4-p23/bin/bash + + echo Hello! + ``` + ## sublist Return a sublist of a given list using a starting and an ending index. @@ -209,13 +301,12 @@ Return a sublist of a given list using a starting and an ending index. Types: - sublist (`function list, ints.positive, ints.positive -> listOf Any`): - - - (`list`): - List to get sublist from. - - (`ints.positive`): - Starting list index. - - (`ints.positive`): - Ending list index. + - (`list`): + List to get sublist from. + - (`ints.positive`): + Starting list index. + - (`ints.positive`): + Ending list index. Example: diff --git a/docs/src/api/extensions/patchers.md b/docs/src/api/extensions/patchers.md deleted file mode 100644 index 50fa309c3..000000000 --- a/docs/src/api/extensions/patchers.md +++ /dev/null @@ -1,67 +0,0 @@ -## pathShebangs - -Replace common [shebangs](https://bash.cyberciti.biz/guide/Shebang) -for their Nix equivalent. - -For example: - -- `#! /bin/env xxx` -> `/nix/store/..-name/bin/xxx` -- `#! /usr/bin/env xxx` -> `/nix/store/..-name/bin/xxx` -- `#! /path/to/my/xxx` -> `/nix/store/..-name/bin/xxx` - -Types: - -- pathShebangs (`package`): - When sourced, - it exports a Bash function called `patch_shebangs` - into the evaluation context. - This function receives one or more files or directories as arguments - and replace shebangs of the executable files in-place. - Note that only shebangs that resolve to executables in the `"${PATH}"` - (a.k.a. `searchPaths.bin`) will be taken into account. - -Example: - -=== "main.nix" - - ```nix - # /path/to/my/project/makes/example/main.nix - { - __nixpkgs__, - makeDerivation, - patchShebangs, - ... - }: - makeDerivation { - env = { - envFile = builtins.toFile "my_file.sh" '' - #! /usr/bin/env bash - - echo Hello! - ''; - }; - builder = '' - copy $envFile $out - - chmod +x $out - patch_shebangs $out - - cat $out - ''; - name = "example"; - searchPaths = { - bin = [ __nixpkgs__.bash ]; # Propagate bash so `patch_shebangs` "sees" it - source = [ patchShebangs ]; - }; - } - ``` - -=== "Invocation" - - ```bash - $ m . /example - - #! /nix/store/dpjnjrqbgbm8a5wvi1hya01vd8wyvsq4-bash-4.4-p23/bin/bash - - echo Hello! - ``` diff --git a/docs/src/api/extensions/python.md b/docs/src/api/extensions/python.md index a88aee5ed..f6c2e8670 100644 --- a/docs/src/api/extensions/python.md +++ b/docs/src/api/extensions/python.md @@ -5,9 +5,8 @@ Get a specific Python interpreter. Types: - makePythonVersion (`function str -> package`): - - - (`enum ["3.8" "3.9" "3.10" "3.11"]`): - Python version of the interpreter to return. + - (`enum ["3.8" "3.9" "3.10" "3.11"]`): + Python version of the interpreter to return. Example: @@ -46,48 +45,48 @@ where a provided set of Python packages from [PyPi](https://pypi.org/) is installed. -Pre-requisites: [Generating a sourcesYaml](#makepythonlock) +Pre-requisites: +[Generating a sourcesYaml](/api/builtins/utilities/#makepythonlock) Types: - makePythonPypiEnvironment (`function { ... } -> package`): - - - name (`str`): - Custom name to assign to the build step, be creative, it helps in debugging. - - searchPathsBuild (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths` - and used while installing the Python dependencies. - Defaults to `makeSearchPaths`'s defaults. - - searchPathsRuntime (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths` - and propagated to the runtime environment. - Defaults to `makeSearchPaths`'s defaults. - - sourcesYaml (`package`): - `sources.yaml` file - computed as explained in the pre-requisites section. + - name (`str`): + Custom name to assign to the build step, be creative, it helps in debugging. + - searchPathsBuild (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths` + and used while installing the Python dependencies. + Defaults to `makeSearchPaths`'s defaults. + - searchPathsRuntime (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths` + and propagated to the runtime environment. + Defaults to `makeSearchPaths`'s defaults. + - sourcesYaml (`package`): + `sources.yaml` file + computed as explained in the pre-requisites section. For building a few special packages you may need to boostrap dependencies in the build environment. The following flags are available for convenience: - - withCython_0_29_24 (`bool`): Optional. - Bootstrap cython 0.29.24 to the environment - Defaults to `false`. - - withNumpy_1_24_0 (`bool`): Optional. - Bootstrap numpy 1.24.0 to the environment - Defaults to `false`. - - withSetuptools_57_4_0 (`bool`): Optional. - Bootstrap setuptools 57.4.0 to the environment - Defaults to `false`. - - withSetuptoolsScm_5_0_2 (`bool`) Optional. - Bootstrap setuptools-scm 5.0.2 to the environment - Defaults to `false`. - - withSetuptoolsScm_6_0_1 (`bool`) Optional. - Bootstrap setuptools-scm 6.0.1 to the environment - Defaults to `false`. - - withWheel_0_37_0 (`bool`): Optional. - Bootstrap wheel 0.37.0 to the environment - Defaults to `false`. + - withCython_0_29_24 (`bool`): Optional. + Bootstrap cython 0.29.24 to the environment + Defaults to `false`. + - withNumpy_1_24_0 (`bool`): Optional. + Bootstrap numpy 1.24.0 to the environment + Defaults to `false`. + - withSetuptools_57_4_0 (`bool`): Optional. + Bootstrap setuptools 57.4.0 to the environment + Defaults to `false`. + - withSetuptoolsScm_5_0_2 (`bool`) Optional. + Bootstrap setuptools-scm 5.0.2 to the environment + Defaults to `false`. + - withSetuptoolsScm_6_0_1 (`bool`) Optional. + Bootstrap setuptools-scm 6.0.1 to the environment + Defaults to `false`. + - withWheel_0_37_0 (`bool`): Optional. + Bootstrap wheel 0.37.0 to the environment + Defaults to `false`. Example: diff --git a/docs/src/api/extensions/ruby.md b/docs/src/api/extensions/ruby.md index 36160467b..fc466b481 100644 --- a/docs/src/api/extensions/ruby.md +++ b/docs/src/api/extensions/ruby.md @@ -5,9 +5,8 @@ Get a specific Ruby interpreter. Types: - makeRubyVersion (`function str -> package`): - - - (`enum [ "2.7" "3.0" "3.1" ]`): - Version of the Ruby interpreter. + - (`enum [ "2.7" "3.0" "3.1" ]`): + Version of the Ruby interpreter. Example: @@ -47,17 +46,16 @@ from the [RubyGems][rubygems]. Types: - makeRubyGemsInstall (`function { ... } -> package`): - - - name (`str`): - Custom name to assign to the build step, be creative, it helps in debugging. - - ruby (`enum [ "2.7" "3.0" ]`): - Version of the Ruby interpreter. - - searchPaths (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths`. - Defaults to `makeSearchPaths`'s defaults. - - sourcesYaml (`package`): - `sources.yaml` file - computed as explained in the pre-requisites section. + - name (`str`): + Custom name to assign to the build step, be creative, it helps in debugging. + - ruby (`enum [ "2.7" "3.0" ]`): + Version of the Ruby interpreter. + - searchPaths (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths`. + Defaults to `makeSearchPaths`'s defaults. + - sourcesYaml (`package`): + `sources.yaml` file + computed as explained in the pre-requisites section. Example: @@ -90,22 +88,21 @@ are available. Types: - makeRubyGemsEnvironment (`function { ... } -> package`): - - - name (`str`): - Custom name to assign to the build step, be creative, it helps in debugging. - - ruby (`enum [ "2.7" "3.0" ]`): - Version of the Ruby interpreter. - - searchPathsBuild (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths` - and used while installing gems. - Defaults to `makeSearchPaths`'s defaults. - - searchPathsRuntime (`asIn makeSearchPaths`): Optional. - Arguments here will be passed as-is to `makeSearchPaths` - and propagated to the runtime environment. - Defaults to `makeSearchPaths`'s defaults. - - sourcesYaml (`package`): - `sources.yaml` file - computed as explained in the pre-requisites section. + - name (`str`): + Custom name to assign to the build step, be creative, it helps in debugging. + - ruby (`enum [ "2.7" "3.0" ]`): + Version of the Ruby interpreter. + - searchPathsBuild (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths` + and used while installing gems. + Defaults to `makeSearchPaths`'s defaults. + - searchPathsRuntime (`asIn makeSearchPaths`): Optional. + Arguments here will be passed as-is to `makeSearchPaths` + and propagated to the runtime environment. + Defaults to `makeSearchPaths`'s defaults. + - sourcesYaml (`package`): + `sources.yaml` file + computed as explained in the pre-requisites section. Example: diff --git a/docs/src/architecture.md b/docs/src/architecture.md index 59edf1455..7d70cb1e7 100644 --- a/docs/src/architecture.md +++ b/docs/src/architecture.md @@ -1,5 +1,10 @@ # Architecture +Below you will find a high-level diagram +of the Makes architecture + +--- + ```mermaid flowchart TB diff --git a/docs/src/contributing.md b/docs/src/contributing.md index c769429c1..293d005d8 100644 --- a/docs/src/contributing.md +++ b/docs/src/contributing.md @@ -58,36 +58,36 @@ a maintainer must follow the following steps to review it: 1. Check that the proposed change has an associated issue, - enough discussion has happened on it, - and there is consensus in the implementation details, - and if we agree that implement it is a good idea. + enough discussion has happened on it, + and there is consensus in the implementation details, + and if we agree that implement it is a good idea. 1. Check if the change modifies the [Architecture](/architecture/) - in any way, and that it has been updated. + in any way, and that it has been updated. 1. Check if the implementation follows the - [Secure Design Principles](/security/design-principles/), - and documents there - any new interactions, - or updates the documentation accordingly. + [Secure Design Principles](/security/design-principles/), + and documents there + any new interactions, + or updates the documentation accordingly. 1. Check if the implementation introduces new threats, - or changes/removes an existing threat, - and if the [Threat Model](/security/threat-model/) - documentation has been updated to reflect it. + or changes/removes an existing threat, + and if the [Threat Model](/security/threat-model/) + documentation has been updated to reflect it. 1. Check if the change adds or modifies - an existing security property of the system, - and if the [Software Assurance](/security/assurance/) - documentation has been updated to reflect it. + an existing security property of the system, + and if the [Software Assurance](/security/assurance/) + documentation has been updated to reflect it. 1. Check if the CI/CD succeeded. - No job should fail - unless something unrelated to the pull request happened. + No job should fail + unless something unrelated to the pull request happened. 1. The _Developer Certificate of Origin_ was accepted, - normally through checking - that the job in the CI/CD that verifies it succeeded. + normally through checking + that the job in the CI/CD that verifies it succeeded. 1. The steps mentioned in the sections above were followed, - particularly check if the code is readable, - maintainable, - proper tests were added or updated, - the corresponding docs were added or updated, - and the architecture and design seems to be of good quality. + particularly check if the code is readable, + maintainable, + proper tests were added or updated, + the corresponding docs were added or updated, + and the architecture and design seems to be of good quality. diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md index feffe3bec..c003fef5d 100644 --- a/docs/src/getting-started.md +++ b/docs/src/getting-started.md @@ -29,9 +29,9 @@ where: - `` is a GitHub, GitLab or local repository. - `` is a Makes job - that exists within the referenced repository. - If no job is specified, - Makes displays all available jobs. + that exists within the referenced repository. + If no job is specified, + Makes displays all available jobs. Example: diff --git a/docs/src/index.md b/docs/src/index.md index 5c780aecf..f181d127d 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -10,13 +10,13 @@ powered by [Nix](https://nixos.org/). Ever needed to - run applications locally - to try out your code? + to try out your code - Execute CI/CD pipelines locally - to make sure jobs are being passed? + to make sure jobs are being passed - Keep execution environments frozen - for strict dependency control - against supply chain attacks? -- Know the exact dependency tree of your application? + for strict dependency control + against supply chain attacks +- Know the exact dependency tree of your application Well, we have! diff --git a/docs/src/security/assurance.md b/docs/src/security/assurance.md index d19a6f585..e46180d3f 100644 --- a/docs/src/security/assurance.md +++ b/docs/src/security/assurance.md @@ -5,64 +5,62 @@ the notation is that of a _Structured Assurance Case Model_[^1]. - The Makes CLI application is free of known security vulnerabilities. - - The Python code of the Makes CLI application - is free of known security vulnerabilities. - - - [SonarCloud](https://sonarcloud.io/) - reviews every pull request. - - Proof: - - - You can check the - [SonarCloud pull requests list for Makes](https://sonarcloud.io/project/pull_requests_list?id=fluidattacks_makes) - - - You can check the - [pull requests history](https://github.com/fluidattacks/makes/pulls) - and see if the latest pull requests - have a comment - from SonarCloud. - For example: - [PR 925, Comment 1256837172](https://github.com/fluidattacks/makes/pull/925#issuecomment-1256837172) - - - Vulnerabilities count on [SonarCloud](https://sonarcloud.io/) is zero. - - Proof: - - - Visit the [SonarCloud dashboard](https://sonarcloud.io/project/overview?id=fluidattacks_makes). - The vulnerabilities count should be zero. - - - The dependencies of the Makes CLI application - are free of known security vulnerabilities. - - - [Dependabot alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) - are enabled for the repository. - - Proof: - - - As a project maintainer, - you can see if Dependabot is enabled - [here](https://github.com/fluidattacks/makes/security/dependabot). - - As an external user, - there is no way to verify - if Dependabot is enabled - because the configuration page for this - is only available to repository maintainers. - However, - it is possible to see the pull requests created by the bot, - for example: - [PR 927](https://github.com/fluidattacks/makes/pull/927). - Additionally, - an external user could check - if there has been Dependabot pull requests recently - by checking the - [pull requests history](https://github.com/fluidattacks/makes/pulls). - It is important to note - that if no recent pull requests exist - it may mean - that no known security vulnerabilities have been found, - and not necessarily that this claim is false. - - + - The Python code of the Makes CLI application + is free of known security vulnerabilities. + + - [SonarCloud](https://sonarcloud.io/) + reviews every pull request. + + Proof: + + - You can check the + [SonarCloud pull requests list for Makes](https://sonarcloud.io/project/pull_requests_list?id=fluidattacks_makes) + + - You can check the + [pull requests history](https://github.com/fluidattacks/makes/pulls) + and see if the latest pull requests + have a comment + from SonarCloud. + For example: + [PR 925, Comment 1256837172](https://github.com/fluidattacks/makes/pull/925#issuecomment-1256837172) + + - Vulnerabilities count on [SonarCloud](https://sonarcloud.io/) is zero. + + Proof: + + - Visit the [SonarCloud dashboard](https://sonarcloud.io/project/overview?id=fluidattacks_makes). + The vulnerabilities count should be zero. + + - The dependencies of the Makes CLI application + are free of known security vulnerabilities. + + - [Dependabot alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) + are enabled for the repository. + + Proof: + + - As a project maintainer, + you can see if Dependabot is enabled + [here](https://github.com/fluidattacks/makes/security/dependabot). + - As an external user, + there is no way to verify + if Dependabot is enabled + because the configuration page for this + is only available to repository maintainers. + However, + it is possible to see the pull requests created by the bot, + for example: + [PR 927](https://github.com/fluidattacks/makes/pull/927). + Additionally, + an external user could check + if there has been Dependabot pull requests recently + by checking the + [pull requests history](https://github.com/fluidattacks/makes/pulls). + It is important to note + that if no recent pull requests exist + it may mean + that no known security vulnerabilities have been found, + and not necessarily that this claim is false. ## References diff --git a/docs/src/security/design-principles.md b/docs/src/security/design-principles.md index 821e07488..6be872951 100644 --- a/docs/src/security/design-principles.md +++ b/docs/src/security/design-principles.md @@ -1,20 +1,20 @@ # Design Principles -## Principle of Least Privilege +## Least Privilege - The Makes CLI is a python application that runs in user-space. The privileges required are: - - Write access to the `${HOME}`, - which is normally owned by the user, - so no extra privileges - other than what the user already has are required. - - Creating temporary files/directories, - which respects the `${TMPDIR}` environment variable, - which is a functionality normally available to a user, - so no extra privileges are required. - - A system with Nix installed. - - (optional) privileges to create Kernel namespaces. + - Write access to the `${HOME}`, + which is normally owned by the user, + so no extra privileges + other than what the user already has are required. + - Creating temporary files/directories, + which respects the `${TMPDIR}` environment variable, + which is a functionality normally available to a user, + so no extra privileges are required. + - A system with Nix installed. + - (optional) privileges to create Kernel namespaces. - The Makes framework is simply a library that aids the developer in creating build scripts, @@ -29,7 +29,7 @@ They are generated as any other build (hermetic, pure, etc) using information from the Nix Store. -## Principle of Fail-Safe Defaults +## Fail-Safe Defaults - By default, builds are run in a sandbox that uses kernel namespaces @@ -63,7 +63,7 @@ and no write binary cache is the default configuration, -## Principle of Economy of Mechanism +## Economy of Mechanism - The Makes CLI is essentially a wrapper over Nix, so the surface is as small as possible (~1000 loc). @@ -72,28 +72,28 @@ saving the user the work of writing that functionality themselves which would require the same amount of code anyway. -## Principle of Complete Mediation +## Complete Mediation -## Principle of Open Design +## Open Design - Makes is Free and Open Source Software, - anyone can read its internals: - https://github.com/fluidattacks/makes + anyone can read its internals: + https://github.com/fluidattacks/makes -## Principle of Separation of Privilege +## Separation of Privilege -## Principle of Least Common Mechanism +## Least Common Mechanism - In the most common case - each user of Makes has a personal `/nix/store` - and a personal installation of Nix. - The `/nix/store` contents are not shared between users by default, - unless the user configures a read+write binary cache - and sets the corresponding binary cache secret. + each user of Makes has a personal `/nix/store` + and a personal installation of Nix. + The `/nix/store` contents are not shared between users by default, + unless the user configures a read+write binary cache + and sets the corresponding binary cache secret. -## Principle of Psychological Acceptability +## Psychological Acceptability - The Makes CLI is easy to use. - Performing an installation using the default values - yields a sufficiently secure version of the system. - Users familiar with other build tools would feel at home. + Performing an installation using the default values + yields a sufficiently secure version of the system. + Users familiar with other build tools would feel at home. diff --git a/docs/src/security/introduction.md b/docs/src/security/index.md similarity index 100% rename from docs/src/security/introduction.md rename to docs/src/security/index.md diff --git a/docs/src/security/slsa.md b/docs/src/security/slsa.md index 454216499..97a6be69d 100644 --- a/docs/src/security/slsa.md +++ b/docs/src/security/slsa.md @@ -44,25 +44,25 @@ For clarity, this is how SLSA definitions map into our infrastructure: - **Source**: Git repository at: - [github.com/fluidattacks/makes][makes]. + [github.com/fluidattacks/makes][makes]. - **Platform**: [GitHub Actions][github_actions], - [Makes][makes], - and the [Nix package manager][nix]. + [Makes][makes], + and the [Nix package manager][nix]. - **Build service**: - [GitHub Actions][github_actions], - using GitHub hosted runners. + [GitHub Actions][github_actions], + using GitHub hosted runners. - **Build**: A Nix derivation. - **Environment**: A sandbox - that [Chroot](https://en.wikipedia.org/wiki/Chroot)s - into an empty temporary directory, - provides private versions - of `/proc`, `/dev`, `/dev/shm`, and `/dev/pts`, - and uses a private PID, mount, network, IPC, and UTS namespace - to isolate itself from other processes in the system. + that [Chroot](https://en.wikipedia.org/wiki/Chroot)s + into an empty temporary directory, + provides private versions + of `/proc`, `/dev`, `/dev/shm`, and `/dev/pts`, + and uses a private PID, mount, network, IPC, and UTS namespace + to isolate itself from other processes in the system. - **Steps**: Instructions declared - in the corresponding Makes configuration files - written using the Nix programming language - and shell scripting, versioned as-code in the _source_. + in the corresponding Makes configuration files + written using the Nix programming language + and shell scripting, versioned as-code in the _source_. ## Source Requirements @@ -72,22 +72,22 @@ Every change to the source is tracked on GitHub, using the Git version control system. - **Change history**: There exists a record - of the history of changes - that went into the revision. - Each change contains: - the identities of the uploader and reviewers (if any), - timestamps of the reviews (if any) and submission, - the change description/justification, - the content of the change, - and the parent revisions. + of the history of changes + that went into the revision. + Each change contains: + the identities of the uploader and reviewers (if any), + timestamps of the reviews (if any) and submission, + the change description/justification, + the content of the change, + and the parent revisions. - For example: [PR 649](https://github.com/fluidattacks/makes/pull/649). + For example: [PR 649](https://github.com/fluidattacks/makes/pull/649). - **Immutable reference**: - There exists a way to indefinitely reference a particular, - immutable revision. - For example: - [c61feb1be11abc4d7ffed52c660a45c57f06599c](https://github.com/fluidattacks/makes/commit/c61feb1be11abc4d7ffed52c660a45c57f06599c). + There exists a way to indefinitely reference a particular, + immutable revision. + For example: + [c61feb1be11abc4d7ffed52c660a45c57f06599c](https://github.com/fluidattacks/makes/commit/c61feb1be11abc4d7ffed52c660a45c57f06599c). ### Verified history @@ -177,18 +177,18 @@ For example: According to the [GitHub Actions documentation](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners), - "Each GitHub-hosted runner - is a new virtual machine (VM) - hosted by GitHub with the runner application - and other tools preinstalled." + is a new virtual machine (VM) + hosted by GitHub with the runner application + and other tools preinstalled." - "When the job begins, - GitHub automatically provisions a new VM for that job. - All steps in the job execute on the VM, - allowing the steps in that job to share information - using the runner's filesystem. - You can run workflows directly on the VM - or in a Docker container. - When the job has finished, - the VM is automatically decommissioned." + GitHub automatically provisions a new VM for that job. + All steps in the job execute on the VM, + allowing the steps in that job to share information + using the runner's filesystem. + You can run workflows directly on the VM + or in a Docker container. + When the job has finished, + the VM is automatically decommissioned." Additionally, the [Nix package manager][nix] @@ -251,14 +251,14 @@ For example: The [Nix package manager][nix]: - Fetches all of the declared artifacts - into a trusted control plane (the /nix/store). + into a trusted control plane (the /nix/store). - Mounts into the build sandbox - the specific /nix/store paths required by it. + the specific /nix/store paths required by it. - Allows a build to fetch artifacts over the network - if and only if the expected artifact integrity is specified. + if and only if the expected artifact integrity is specified. - Validates the integrity of each artifact - before allowing a build to use it, - and fails the build if the verification fails. + before allowing a build to use it, + and fails the build if the verification fails. - Denies network connectivity if no expected hash is specified. ### Reproducible @@ -313,18 +313,18 @@ The provenance cannot be falsified by the build service's users: - There is no secret material - to demonstrate the non-falsifiable nature of the provenance - (see _Provenance - Authenticated_). + to demonstrate the non-falsifiable nature of the provenance + (see _Provenance - Authenticated_). - Even if such secret material existed, - builds are run in an hermetic environment, - and therefore they wouldn't be available to the build steps - (see _Build - Hermetic_). + builds are run in an hermetic environment, + and therefore they wouldn't be available to the build steps + (see _Build - Hermetic_). - Every field in the provenance is generated - by the build service in a trusted control plane, - which is fully defined by the build configuration, - which comes directly from the Source, - and therefore is as secure as the Source is - (see _Source - Verified History_). + by the build service in a trusted control plane, + which is fully defined by the build configuration, + which comes directly from the Source, + and therefore is as secure as the Source is + (see _Source - Verified History_). ### Dependencies Complete diff --git a/docs/src/security/threat-model.md b/docs/src/security/threat-model.md index 2d75e75aa..98d9f21bc 100644 --- a/docs/src/security/threat-model.md +++ b/docs/src/security/threat-model.md @@ -3,28 +3,28 @@ ## Spoofing - A user can mistype the Makes installation command - and wrongly install a different (potentially malicious) tool. + and wrongly install a different (potentially malicious) tool. - Mitigation: + Mitigation: - - The installation command is given in plain-text, - users can copy-paste it to avoid typos. + - The installation command is given in plain-text, + users can copy-paste it to avoid typos. - A user can mistype the target project to be built with Makes, - and end-up building (and potentially running) - a different (potentially malicious) project. + and end-up building (and potentially running) + a different (potentially malicious) project. - Mitigation: + Mitigation: - - The most common use case - (running makes on the project in the current working directory) - has a very convenient syntax: `$ m .`, - which is very unlikely to be mistyped. - - When referencing a project over the internet, - the user is forced to use a git provider (github/gitlab), - the owner account (which should be trusted by the user), - the target repository, - and a branch, commit or tag. + - The most common use case + (running makes on the project in the current working directory) + has a very convenient syntax: `$ m .`, + which is very unlikely to be mistyped. + - When referencing a project over the internet, + the user is forced to use a git provider (github/gitlab), + the owner account (which should be trusted by the user), + the target repository, + and a branch, commit or tag. By using a commit, the user can force the integrity of the downloaded data @@ -33,114 +33,118 @@ ## Tampering - The Nix Store can be tampered with - if no good installation measures are taken by the user. + if no good installation measures are taken by the user. - Mitigation: + Mitigation: - - The Nix installation is responsibility of the user, - but in general, - a user could bind mount `/nix` as a read-only file system, - and make the `/nix/store` only accessible by root - and the `nixbld` group users, - reducing an attack vector to the physical or local layer, - which can be further protected - by the use of frameworks like [SLSA](https://slsa.dev/), - and full disk encryption using [LUKS](https://en.wikipedia.org/wiki/LUKS). + - The Nix installation is responsibility of the user, + but in general, + a user could bind mount `/nix` as a read-only file system, + and make the `/nix/store` only accessible by root + and the `nixbld` group users, + reducing an attack vector to the physical or local layer, + which can be further protected + by the use of frameworks like [SLSA](https://slsa.dev/), + and full disk encryption using [LUKS](https://en.wikipedia.org/wiki/LUKS). ## Repudiation - In single tenant setups, - for instance when developers run Makes in their laptops, - there is nothing to repudiate, - there is only one user performing builds (the developer). - However, - in multi-tenant setups, - for instance when Makes is run in a shared CI/CD system, - a user could deny running a build. - - Mitigation: - - - Makes produces - [SLSA Provenance Attestations](https://slsa.dev/provenance/v0.2), - which identify the builder and the built artifact. - - Most CI/CD systems - (and particularly the ones supported by Makes) - offer logs collection, - so it would be easy to associate a build - with the identity that triggered it. - It is responsibility of the users - to configure such CI/CD systems - in a secure way and to protect (and backup) the logs. + for instance when developers run Makes in their laptops, + there is nothing to repudiate, + there is only one user performing builds (the developer). + However, + in multi-tenant setups, + for instance when Makes is run in a shared CI/CD system, + a user could deny running a build. + + Mitigation: + + - Makes produces + [SLSA Provenance Attestations](https://slsa.dev/provenance/v0.2), + which identify the builder and the built artifact. + - Most CI/CD systems + (and particularly the ones supported by Makes) + offer logs collection, + so it would be easy to associate a build + with the identity that triggered it. + It is responsibility of the users + to configure such CI/CD systems + in a secure way and to protect (and backup) the logs. ## Information Disclosure - Although the `/nix/store` is individual per user, - a user may write secrets to it, - and then those secrets can be published to a binary cache - that is publicly accessible. - - Examples of this include Nix idioms like: - - ```nix - [ - // Nix would load the secrets in plain-text to the `/nix/store` - ./file-with-secrets-in-plain-text.txt - - // Nix would load the git repository to the `/nix/store` - // This also applies to other builtins.fetch* that could - // fetch private information - (builtins.fetchGit { - // Private repository (with potential intellectual property) - url = "git@github.com:company/secrets.git"; - }) - ] - ``` - - Mitigation: - - - Nothing from the `/nix/store` - is pushed to a binary cache by default. - A user would need to configure the cache explicitly, - and expose the corresponding secret - in an environment variable. - - Makes has support for binary caches - that require a secret for reading and writting, - so a user may chose to use this instead - as an extra layer of prevention - if loading secrets to the `/nix/store` is mandatory. - Please see for more information. - - Makes has utilities for working with secrets in a way - that they are only copied to the `/nix/store` - in encrypted form, - and then decrypted at runtime, - where there are safe from disclosure. - - For example: - `secretsForAwsFromEnv`, - `secretsForAwsFromGitlab`, - `secretsForEnvFromSops`, - `secretsForGpgFromEnv`, - `secretsForKubernetesConfigFromAws`, and - `secretsForTerraformFromEnv`. - - However, we don't currently have a way to protect the user - from using `builtins.fetch*`. - If your workflow needs this, - please avoid pushing artifacts to a public binary cache, - or use a private binary cache instead. - - - Makes copies the contents of the git repository - into a trusted control plane, - and excludes all of the files - that are not tracked by Git - from this checkout. - This means that if the file with secrets is inside the repository, - but included in the `.gitignore` - such that a `git fetch` of the given remote and revision - would ignore it, - Makes would not copy it into the trusted control plane, - and therefore Nix wouldn't load it into the `/nix/store`. + a user may write secrets to it, + and then those secrets can be published to a binary cache + that is publicly accessible. + + Examples of this include Nix idioms like: + + ```nix + [ + // Nix would load the secrets in plain-text to the `/nix/store` + ./file-with-secrets-in-plain-text.txt + + // Nix would load the git repository to the `/nix/store` + // This also applies to other builtins.fetch* that could + // fetch private information + (builtins.fetchGit { + // Private repository (with potential intellectual property) + url = "git@github.com:company/secrets.git"; + }) + ] + ``` + + Mitigation: + + - Nothing from the `/nix/store` + is pushed to a binary cache by default. + A user would need to configure the cache explicitly, + and expose the corresponding secret + in an environment variable. + - Makes has support for binary caches + that require a secret for reading and writting, + so a user may chose to use this instead + as an extra layer of prevention + if loading secrets to the `/nix/store` is mandatory. + Please see for more information. + - Makes has utilities for working with secrets in a way + that they are only copied to the `/nix/store` + in encrypted form, + and then decrypted at runtime, + where there are safe from disclosure. + + For example: + `secretsForAwsFromEnv`, + `secretsForAwsFromGitlab`, + `secretsForEnvFromSops`, + `secretsForGpgFromEnv`, + `secretsForKubernetesConfigFromAws`, and + `secretsForTerraformFromEnv`. + + However, we don't currently have a way to protect the user + from using `builtins.fetch*`. + If your workflow needs this, + please avoid pushing artifacts to a public binary cache, + or use a private binary cache instead. + + - Makes copies the contents of the git repository + into a trusted control plane, + and excludes all of the files + that are not tracked by Git + from this checkout. + This means that if the file with secrets is inside the repository, + but included in the `.gitignore` + such that a `git fetch` of the given remote and revision + would ignore it, + Makes would not copy it into the trusted control plane, + and therefore Nix wouldn't load it into the `/nix/store`. ## Denial of Service +WIP + ## Elevation of Privileges + +WIP