{"id":26471316,"url":"https://github.com/adevinta/vulcan-local","last_synced_at":"2025-10-30T20:08:01.847Z","repository":{"id":38081680,"uuid":"460381731","full_name":"adevinta/vulcan-local","owner":"adevinta","description":"Scan your local assets with Vulcan-checks on your local machine or in CI/CD.","archived":false,"fork":false,"pushed_at":"2024-07-01T15:15:16.000Z","size":509,"stargazers_count":10,"open_issues_count":4,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-10-19T14:53:54.691Z","etag":null,"topics":["security","vulcan"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adevinta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-17T10:14:52.000Z","updated_at":"2025-07-16T23:23:52.000Z","dependencies_parsed_at":"2024-06-19T19:04:02.553Z","dependency_job_id":null,"html_url":"https://github.com/adevinta/vulcan-local","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/adevinta/vulcan-local","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adevinta%2Fvulcan-local","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adevinta%2Fvulcan-local/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adevinta%2Fvulcan-local/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adevinta%2Fvulcan-local/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adevinta","download_url":"https://codeload.github.com/adevinta/vulcan-local/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adevinta%2Fvulcan-local/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281873485,"owners_count":26576262,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-30T02:00:06.501Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["security","vulcan"],"created_at":"2025-03-19T20:54:04.690Z","updated_at":"2025-10-30T20:08:01.829Z","avatar_url":"https://github.com/adevinta.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vulcan-local\n\nvulcan-local allows to execute security checks locally.\n\n- Is part of **Vulcan vulnerability scanning** ecosystem. See \u003chttps://adevinta.github.io/vulcan-docs/\u003e\n- Leverages [vulcan-checks](https://github.com/adevinta/vulcan-checks) catalog.\n- The checks are executed in your local machine or in a CI/CD pipeline.\n- Only `docker` and `git` are required.\n- The checks can access local assets.\n  - Local directories.\n  - Local docker images.\n  - Local http applications.\n\nFor those reasons this tool can be a good fit to move left security.\n\n## Requirements\n\n- Docker has to be running on the local machine.\n- Git.\n- Go (for development)\n\n## Installing\n\nFrom source code\n\n```sh\n# Last release version\ngo install github.com/adevinta/vulcan-local@latest\n```\n\nInstall binary releases\n\n```sh\n# Install last release\ncurl -sfL https://raw.githubusercontent.com/adevinta/vulcan-local/master/script/get | sh\n\n# Install specific version\ncurl -sfL https://raw.githubusercontent.com/adevinta/vulcan-local/master/script/get | sh -s -- --version v0.0.1\n\n# Show available options\ncurl -sfL https://raw.githubusercontent.com/adevinta/vulcan-local/master/script/get | sh -s -- --help\nAccepted cli arguments are:\n  [--help|-h ] -\u003e\u003e prints this help\n  [--version|-v \u003cdesired_version\u003e] . When not defined it fetches the latest release from GitHub\n  [--no-sudo]  -\u003e\u003e install without sudo\n  [--run|--] ... -\u003e\u003e Skip install and run the downloaded vulcan-local temp binary with the extra params\n\n# Executing without installing\ncurl -sfL https://raw.githubusercontent.com/adevinta/vulcan-local/master/script/get | sh -s -- \\\n  --run -t .\n```\n\n## Executing\n\nSee some examples\n\n```sh\n# Show available options\nvulcan-local -h\n\n# Scan current directory as a git repo with the default checktypes.\nvulcan-local -t .\n\n# Scan a remote public docker image\nvulcan-local -t alpine:latest -a DockerImage\n\n# Build and scan a local image\necho \"FROM alpine\" | docker build -t myimg -\nvulcan-local -t myimg -a DockerImage\n\n# Scan the local http endpoint with the custom checktypes.\ndocker run -d -p 1234:80 --name myapp nginx\nvulcan-local -t http://localhost:1234 -i exposed\n\n# Execute all checks on WebAddress that doesn't matches 'zap' regex.\nvulcan-local -t http://localhost:1234 -e zap\n\n# Execute all checks on WebAddress with the indicated option.\nvulcan-local -t http://localhost:1234 -o '{\"depth\": 1}'\n\n# Execute all checks . inferring the asset type.\nvulcan-local -t .\n\n# See the report in json\nvulcan-local -t . -r - -l ERROR | jq .\n\n# Pass variables trough command line (those examples are equivalent)\nvulcan-local -t https://wordpress.org -i wpscan -v WPVULNDB_API_TOKEN\nvulcan-local -t https://wordpress.org -i wpscan -v WPVULNDB_API_TOKEN=$WPVULNDB_API_TOKEN\n```\n\nAlso the tool can be used to scan remote resources.\n\n```sh\n# Scan a list of assets for CRITICAL vulns with trivy exporting the results in json.\ncat myimages.txt | awk '{print \"-t \" $0 \" -a DockerImage\"}' \\\n  | xargs -p vulcan-local -i trivy -s CRITICAL -r report.json\n\n# Scan all the AWS internet-facing LoadBalancers in one account with all checks available.\naws elbv2 describe-load-balancers \\\n  | jq -r '.LoadBalancers[] | select( .Scheme == \"internet-facing\") | .DNSName' \\\n  | awk '{print \"-t \" $0}' \\\n  | xargs -p vulcan-local -s HIGH -r report.json\n```\n\n## Exit codes\n\n`vulcan-local` generates meaningful exit codes.\n\nExit codes:\n\n- 0: No vulnerability found over the severity threshold (see -s flag)\n- 1: An error happened\n- 101: Max severity found was LOW\n- 102: Max severity found was MEDIUM\n- 103: Max severity found was HIGH\n- 104: Max severity found was CRITICAL\n\nThose exit codes can be used in automated systems like CI/CD to control\nexecution of the pipelines. See example below.\n\n```sh\n#!/bin/bash\n\n# Exit the script in case of error\nset -e\n\ndocker build . -t example.com/org/myimg:latest\n\n# Exit script in case of CRITICAL/HIGH vulnerabilities\nvulcan-local -t . -t example.com/org/myimg:latest -s HIGH\n\ndocker push example.com/org/myimg:latest\n```\n\n## vulcan.yaml config file\n\nThis tool accepts a configuration file that wraps all the parameters.\n\nAn example file is provided in [vulcan.yaml](./vulcan.yaml).\n\nThe main sections are:\n\n- conf/vars: Some config vars sent to the checks, i.e. to allow access to private resources.\n- conf/repositories: http or file uris pointing to checktype definitions.\n- targets: Contains the list of targets to scan. The tool will generate all the possible checks from the checktypes available.\n- checks: The list of additional specific checks to run.\n- reporting: Configuration about how to show the results, exclusions, ...\n\nThis is a very simple config file with two checks:\n\n```yaml\nconf:\n  repositories:\n    - ./resources/checktypes.json\n\n# List of targets to scan generating checks from all available checktypes\ntargets:\n  - target: .\n  - target: http://localhost:1234/\n\n# List of specific additional checks to run\nchecks:\n  # Check current path\n  - type: vulcan-gitleaks\n    target: .\n\nreporting:\n```\n\n### Exclusions\n\nIn case the tool reports a finding that should be excluded from the next scans, it is possible to apply some filtering.\n\nWhen specified, it applies a `contains` evaluation over the following fields:\n\n- summary\n- affectedResource: Applies either to `affectedResource` and `affectedResourceString`\n- target\n- fingerprint\n- description: A brief explanation as to why the finding should be excluded from the report.\n\n```yaml\nreporting:\n  exclusions:\n    - summary: Leaked\n    - affectedResource: libgcrypt\n      target: .\n      description: \"libgcrypt has a known and accepted vulnerability.\"\n    - affectedResource: busybox\n      target: .\n      description: \"busybox is not relevant\"\n    - affectedResource: ncurses\n      target: latest\n    - fingerprint: 7820aa24a96f0fcd4717933772a8bc89552a0c1509f3d90b14d885d25e60595f\n```\n\n### Policies\n\nPolicies in vulcan-local are intended to abstract the overhead selecting checks and options to scan a given target. By default, policies are loaded from the [internal-policies.yaml](https://raw.githubusercontent.com/adevinta/vulcan-local/master/resources/internal-policies.yaml) file.\n\nUse `-p` to set a policy for the scan. Existing default policies are:\n|Policy|Checks included|Target Asset Type|\n|--|--|--|\n|`internal-static`|[vulcan-semgrep](https://github.com/adevinta/vulcan-checks/tree/master/cmd/vulcan-semgrep)\u003cbr\u003e [vulcan-gitleaks](https://github.com/adevinta/vulcan-checks/tree/master/cmd/vulcan-gitleaks)\u003cbr\u003e[vulcan-trivy](https://github.com/adevinta/vulcan-checks/tree/master/cmd/vulcan-trivy)| Git repository \u003cbr\u003eDirectory|\n|`internal-web`|[vulcan-retirejs](https://github.com/adevinta/vulcan-checks/tree/master/cmd/vulcan-retirejs)\u003cbr\u003e[vulcan-zap](https://github.com/adevinta/vulcan-checks/tree/master/cmd/vulcan-zap)\u003cbr\u003e[vulcan-exposed-http](https://github.com/adevinta/vulcan-checks/tree/master/cmd/vulcan-exposed-http)| URL\u003cbr\u003eHostname |\n\nExample:\n```sh\nvulcan-local -p internal-static -t .\n```\n\nCustom policies can be also loaded from a configuration file (local or remote) using `-c` , and then the policy to apply can be set using the parameter `-p`, for example:\n\n```sh\n# Configuration file set through an env variable\nexport VULCAN_CONFIG=https://example.com/custom-policies.yaml\n# Run vulcan-local with 'my-policy'\nvulcan-local -p my-policy -t .\n\n# or just\nvulcan-local -c ./custom-policies.yaml -p my-policy -t .\n```\n\n## Running custom checks\n\nEvery check is a docker image that needs to be pulled from a registry.\n\nWe provide public images for the [vulcan-checks](https://github.com/vulcan-checks).\n\n### Running checks from private registries\n\nThis application does not handle authentication in private registries\ninstead it assumes the current docker client is already authenticated in the required registries.\nIf the check images are from private registries first login into the registry.\n\n```sh\ncat ~/my_password.txt | docker login --username foo --password-stdin private.registry.com\n```\n\n### Running checks from source code\n\n`vulcan-local` can run checks which code is stored locally, to do so point the\nchecktypes param to a directory containing the code of the checktypes to run.\nFor instance, the following command runs the `vulcan-nuclei` check, by building\nand running the code and the docker image in the directory\n`vulcan-checks/cmd/vulcan-nuclei` against the hostname: `example.com`\n\n```bash\ngit clone https://github.com/adevinta/vulcan-checks/\n\n## Make some changes in vulcan-checks/cmd i.e. in vulcan-nuclei.\n\nvulcan-local -checktypes \"./vulcan-checks/cmd\" -t example.com -a Hostname -l debug -i vulcan-nuclei\n```\n\nAt this moment, all the available checks are implemented in [Go](https://go.dev).\nFor that reason it's required to have `go` installed in the system.\n\n## Docker usage\n\nUsing the existing docker image:\n\n```sh\ndocker pull adevinta/vulcan-local:latest\n```\n\nBuilding your local docker image:\n\n```sh\ndocker build . -t vulcan-local\n```\n\nIn the following examples the local image reference `vulcan-local` will e used.\n\nStart the target application\n\n```sh\ndocker run -p 1234:8000 --restart unless-stopped -d appsecco/dsvw\n```\n\nStart scan using a local config file\n\n```sh\ndocker run --rm -v /var/run/docker.sock:/var/run/docker.sock \\\n    -v $PWD:/target \\\n    -e TRAVIS_BUILD_DIR=/target -e REGISTRY_SERVER -e REGISTRY_USERNAME -e REGISTRY_PASSWORD \\\n    vulcan-local -c /target/vulcan.yaml\n```\n\nStart scanning a local http server\n\n```sh\ndocker run --rm -v /var/run/docker.sock:/var/run/docker.sock \\\n    vulcan-local -t http://localhost:1234\n```\n\nStart scanning a local directory\n\n```sh\ndocker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v $PWD:/src \\\n  vulcan-local -t /src\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadevinta%2Fvulcan-local","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadevinta%2Fvulcan-local","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadevinta%2Fvulcan-local/lists"}