Skip to content

Contributing

Thanks for your interest in vpcatlas. The project is small and read-only by design; please keep it that way. The source is at https://github.com/vpcatlas/vpcatlas. This page is the same guide as CONTRIBUTING.md in the repository, with the links adapted to this site.

Setup

git clone https://github.com/vpcatlas/vpcatlas.git
cd vpcatlas
make install        # pip install -e ".[dev]"
make lint test

Requirements: Python 3.12 or newer. These targets of the Makefile are the ones you will use:

Command What it does
make install Installs the package in editable mode with the development tools.
make lint Runs ruff check and ruff format --check on src and tests.
make format Formats src and tests with ruff.
make test Runs the test suite with pytest.
make run Starts the dashboard on port 8080.
make docker-build Builds the image from deploy/Dockerfile.
make binary Builds the one-file binary with PyInstaller for the machine you are on.
make docs Builds this documentation site with mkdocs-material into site/, failing on a broken link.

Where things live: Architecture describes the pipeline and the modules, Model the resources and edges, Coverage every AWS call, and Diagram style the rules for draw.io and Lucid output.

Workflow

  • Branch from main as feat/<scope> or fix/<scope>.
  • Open a pull request to main. Direct commits to main are not accepted.
  • Keep commits small and focused. Write messages in the imperative, with a scope: feat(exporters): nest availability zones inside subnets.
  • Every pull request needs passing make lint and make test.

Code rules

  • Language: all code, comments, docs and commit messages are in English.
  • Python 3.12, full type hints, pydantic v2 models for data structures.
  • Formatting and lint with ruff, line length 110. The pre-commit hook runs it (pre-commit install).
  • New dependencies need a reason in the pull request. Add them to pyproject.toml.
  • Collectors must paginate, must skip AccessDenied per service and must not write to AWS. A denied call becomes a gap, never an exception, and never a zero where a number could not be read.
  • A new AWS call also goes into the auditor policy (src/vpcatlas/auditor-policy.json, and its copy in deploy/iam/), into Coverage and into IAM.
  • Secret values never reach the graph. If a new call returns keys or credentials, strip them in the collector.

Tests

  • Use pytest with moto. Tests must not call real AWS.
  • Fixtures build one VPC, two subnets, an internet gateway, a NAT gateway, a Transit Gateway attachment and a peering with an external account. Use fake account ids such as 111111111111 and 222222222222.
  • Exporter tests check that the draw.io XML parses and that containers are nested.

Documentation

When you change a command, a route, a permission or an output format, update the README, the matching file in docs/ and CHANGELOG.md in the same pull request. The pages of this site are the files in docs/.

Reporting problems

Open an issue at https://github.com/vpcatlas/vpcatlas/issues. For a scan problem, include the version (vpcatlas --version), the command without secrets, and the log of a run with -v. Do not paste account ids, ARNs or a graph file if you do not want them public; describe the shape of the network instead.