diff --git a/README.md b/README.md index a27e0f262..dc9ac260e 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,15 @@ $ go-getter github.com/foo/bar ./foo The command is useful for verifying URL structures. +## Security +Fetching resources from user-supplied URLs is an inherently dangerous operation and may +leave your application vulnerable to [server side request forgery](https://owasp.org/www-community/attacks/Server_Side_Request_Forgery), +[path traversal](https://owasp.org/www-community/attacks/Path_Traversal), [denial of service](https://owasp.org/www-community/attacks/Denial_of_Service) +or other security flaws. + +go-getter contains mitigations for some of these security issues, but should still be used with +caution in security-critical contexts. See the available [security options](#Security-Options) that +can be configured to mitigate some of these risks. ## URL Format go-getter uses a single string URL as input to download from a variety of @@ -361,3 +370,79 @@ In order to access to GCS, authentication credentials should be provided. More i #### GCS Testing The tests for `get_gcs.go` require you to have GCP credentials set in your environment. These credentials can have any level of permissions to any project, they just need to exist. This means setting `GOOGLE_APPLICATION_CREDENTIALS="~/path/to/credentials.json"` or `GOOGLE_CREDENTIALS="{stringified-credentials-json}"`. Due to this configuration, `get_gcs_test.go` will fail for external contributors in CircleCI. + + +### Security Options + +**Disable Symlinks** + +In your getter client config, we recommend using the `DisableSymlinks` option, +which prevents writing through or copying from symlinks (which may point outside the directory). + +```go +client := getter.Client{ + // This will prevent copying or writing files through symlinks + DisableSymlinks: true, +} +``` + +**Disable or Limit `X-Terraform-Get`** + +Go-Getter supports arbitrary redirects via the `X-Terraform-Get` header. This functionality +exists to support [Terraform use cases](https://www.terraform.io/language/modules/sources#http-urls), +but is likely not needed in most applications. + +For code that uses the `HttpGetter`, add the following configuration options: + +```go +var httpGetter = &getter.HttpGetter{ + // Most clients should disable X-Terraform-Get + // See the note below + XTerraformGetDisabled: true, + // Your software probably doesn’t rely on X-Terraform-Get, but + // if it does, you should set the above field to false, plus + // set XTerraformGet Limit to prevent endless redirects + // XTerraformGetLimit: 10, +} +``` + +**Enforce Timeouts** + +The `HttpGetter` supports timeouts and other resource-constraining configuration options. The `GitGetter` and `HgGetter` +only support timeouts. + +Configuration for the `HttpGetter`: + +```go +var httpGetter = &getter.HttpGetter{ + // Disable pre-fetch HEAD requests + DoNotCheckHeadFirst: true, + + // As an alternative to the above setting, you can + // set a reasonable timeout for HEAD requests + // HeadFirstTimeout: 10 * time.Second, + + // Read timeout for HTTP operations + ReadTimeout: 30 * time.Second, + + // Set the maximum number of bytes + // that can be read by the getter + MaxBytes: 500000000, // 500 MB +} +``` + +For code that uses the `GitGetter` or `HgGetter`, set the `Timeout` option: +```go +var gitGetter = &getter.GitGetter{ + // Set a reasonable timeout for git operations + Timeout: 5 * time.Minute, +} +``` + +```go +var hgGetter = &getter.HgGetter{ + // Set a reasonable timeout for hg operations + Timeout: 5 * time.Minute, +} +``` +