# natlas keeps a searchable atlas of your own attack surface

> natlas is an Apache-2.0 platform for continuous scanning of the estate you own, built from an Elasticsearch node, a server that orchestrates agents and scan configuration, and agents that run the nmap based scans, with the goal of reviewing exposure rather than chasing vulnerabilities.

**natlas/natlas** — Attack Surface Management since before Attack Surface Management was a thing

- Repository: https://github.com/natlas/natlas
- Stars: 660 · Forks: 91
- Language: Python
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/natlas-natlas

## An atlas of scans, not a vulnerability report

natlas describes itself as attack surface management since before attack surface management was a thing, and the README's opening metaphor is a map book: you have a lot of maps and they are getting unruly, so you put them in a book and call it an atlas. This one is a website and a collection of nmaps.

The stated objective is to make continuous scanning easy and to make the collected data reviewable. And the goal is spelled out in terms that distinguish it from a vulnerability scanner: the goal is not to identify a bunch of vulnerabilities, necessarily, but rather to identify exposure.

The examples given make the scope concrete. You might want to make sure that no one is running SSH with password authentication enabled. You might want to look for exposed NFS, SMB or rsync shares. You might want to look for expiring or expired SSL certificates, or for weak SSL ciphers in use. These are configuration and exposure questions, and they are the kind that a scan of your own estate can answer repeatedly and cheaply.

That framing also explains the use of nmap as the scanning engine. Because the project sits on the popular nmap port scanner, the README notes you can easily use any default nmap scripts in your scans, which means the tool inherits nmap's script ecosystem rather than trying to reimplement service probing.

For the audience, this is a defender's tool: a team that has infrastructure to keep track of and wants the inventory to update itself rather than producing a report once a quarter.

## Elasticsearch, a server and one or more agents

The deployment is three components, and the README is explicit that you need all of them, with a minimum of one Elasticsearch node, one natlas server and one natlas agent. The quickest arrangement is to run all three containers on the same server. The required order is Elasticsearch first, then the server, then the agents.

The ordering is not arbitrary. The server requires a connection to Elasticsearch in order to launch correctly, so the store has to exist before the application that talks to it. If you have never used Elasticsearch, the README points at Elastic's own instructions for setting up a single node cluster with Docker, with a specific warning to pay attention to the section on persisting the Elastic data, which is the part people skip and then lose their scan history.

The server and the agent have distinct roles, and the split is what allows the scanning to scale across networks. The natlas server controls agent orchestration and scan configuration, and provides search and browse over the data stored in Elastic. The natlas agent is what fetches work from the server and actually performs the scans. The server decides what to scan and with which configuration; the agent does the work wherever it can reach the targets, which is the part that has to live inside the network being inventoried.

Since June 15, 2020 the project has moved to a docker-only deployment model, and there are published container images for both halves, natlas/server and natlas/agent, on Docker Hub, with download badges for each. Installation instructions for the server and the agent live in their own readme files rather than in the root document, so the root README is a map of the system rather than a manual for it.

## From a scan to a record you can query

The data flow follows from that component split, and it is where the value of the design sits.

An agent fetches work from the server. It performs the scan with nmap, and the resulting data is written into Elasticsearch, which is the search and browse layer the server exposes. So the artefact you end up with is not a per-scan report file but a queryable store where a service, a host or a finding can be looked up across the whole estate and across time.

That is the difference between running nmap on a schedule and keeping an atlas. A scheduled nmap produces a new set of outputs every run and leaves you to diff them yourself. A store that holds scan results lets you ask what the estate looks like now, what changed since last time, and what a particular host has exposed for months. The project description in the repository topics names the same idea, with attack surface management, reconnaissance and scanning among the tags, and the CHANGELOG at the root of the repository is the file to read for what has changed between versions.

The acknowledgements also point at where some of the behaviour came from. The initial project, nweb, was created by Dean Pierce and natlas was built out of it, and the copyright notice in the licence retains Intel Corporation for 2016 to 2018 alongside the current author. Ross Snider is credited with writing the Cyclic PRNG used for target selection, which is the mechanism for spreading scans across a target list rather than hammering the same host on every pass. Pinguino created the logo and branding.

One boundary is worth naming: the platform is a scanner and an inventory, so its output is what the scan reached and what it observed. The README is careful that the goal is exposure rather than vulnerability identification, and the data supports questions about configuration and reachability rather than a judgement about exploitability.

## The development stack reveals the real dependency set

The compose file in the repository is labelled for development use only, with a banner telling you not to use it in production. Even so, it is the clearest statement of what a natlas deployment needs, and it names four backing services.

Elasticsearch is there, pinned to a specific 7.x tag, running as a single node with security enabled and a memory lock, and the health check greps the cluster health output for a green or yellow status:

```yaml
  elastic:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.17.18
    container_name: elastic
```

Alongside it is MinIO, which provides an S3 compatible endpoint on 9000 with a console on 9001. That is where scan artefacts live, the raw output that the index in Elasticsearch summarises:

```yaml
  minio:
    image: minio/minio:latest
    container_name: minio
    ports:
      - "9000:9000" # S3 API
```

PostgreSQL is the third service, and the last piece is an OpenTelemetry collector, configured by a separate development file at the root. So the data path runs from the agent, through the server, into Elasticsearch for querying and into object storage for the raw artefacts, with Postgres holding the application's own state and the collector carrying the telemetry out.

Every one of these is an operational commitment. The README's own description of a quick start, running all three containers on one server, is a reasonable way to evaluate the tool. It is not a description of a production topology, and anyone reading the dev compose file as a deployment template will inherit credentials that are literally labelled as not to be used.

## Python 3.12, strict typing and a linter for everything

The project metadata gives the interpreter floor and the version. The package is named natlas, it requires Python 3.12 or later, and the version field reads 0.6.12, which matches the newest published release tag.

The typing configuration is unusually strict for a project of this size. mypy runs in strict mode with strict optional checking, warn unreachable enabled, no implicit re-export, local partial types, and the pydantic plugin, with a separate pydantic-mypy section that forbids extra fields on initialisation and requires typed initialisation. Two error codes are disabled, import-untyped and no-untyped-call, which is a pragmatic concession rather than an oversight, and the migrations directory is excluded, with a comment explaining the odd detail that the exclude path is relative to the server package while mypy is invoked from within it.

Linting is Ruff, configured inline in the same file, selecting the bugbear, comprehensions, pyflakes, flynt, isort, pylint, return, Ruff, simplify, tidy-imports and pyupgrade rule sets, with a handful of pylint complexity rules ignored and relative imports banned outright. A pre-commit configuration is present at the root and a pre-commit badge is in the README, so the checks run before code lands rather than at review time.

One line in that file is worth reading twice: the tool.uv section declares that uv does not manage this pyproject, that the file has no dependencies, and that it exists purely for pre-commit linting and mypy so that all code is standardised. The actual runtime dependencies live in the server and agent packages. It is a small thing, but it is the kind of clarity that saves a new contributor from trying to install the wrong thing.

## Apache 2.0, and a release history that has stopped

The licence is Apache 2.0, and the copyright block carries two holders, 0xdade for 2020 and Intel Corporation for 2016 to 2018, which reflects the project's origin in nweb.

The README also carries a disclaimer that is unusual and worth reading. Natlas is a platform which makes use of many other open source projects, many of which have their own licences. It does not claim ownership of the projects it uses, and does not represent any of them, and the author states that to the best of their knowledge the use of these tools is not violating any licences. The project is free and open source and makes no revenue from the other open source tools it uses. For further inquiry about licensing, the README points to the respective projects' licences.

That is the honest position for a scanner platform that wraps nmap, Elasticsearch, MinIO and others, and it points at a real obligation: the licences of the bundled tools travel with the deployment, and a project that ships those tools inside a container inherits the need to comply with them.

The release history is the part that gives a prospective adopter pause. The listed releases are v0.6.12 on 2020-08-25, v0.6.11 on 2020-08-15 and v0.6.10 on 2020-04-17. Meanwhile the repository is not archived and the last push was on 2026-10-19. In other words, the tagged releases stop in 2020 while the source tree has continued to move for years. The Docker Hub images referenced in the README are therefore unlikely to correspond to the current code, and anyone deploying this needs to decide deliberately between the published images and a build from the current main branch.

The project also carries the governance files a security tool should have: CONTRIBUTING.md with a project setup section, a CODE_OF_CONDUCT.md, and a SECURITY.md that covers the security reporting guidelines and the security related functionality of the platform itself.

## Conclusion

natlas fits a security team that owns a range of internal and external infrastructure and wants a running inventory of what is exposed rather than a point-in-time report, and that is willing to run an Elasticsearch cluster and a set of scanning agents. It is the wrong choice for a single host, where a periodic nmap run and a report is enough, and it is the wrong choice if you cannot accept an operational dependency on Elasticsearch. Before deploying it, read the server and agent readme installation sections in full, because the root README only gives the order of the three components, and check the version you pull, since the published release tags stop at 0.6.12 in 2020 while the repository itself has been pushed to as recently as 2026-10-19.

## FAQ

### What is natlas and what does it scan with?

Natlas is a platform for continuous scanning and reviewing of collected data, used to identify exposure rather than vulnerabilities. It uses the nmap port scanner, so default nmap scripts can be used in scans.

### What components does a natlas deployment need?

A minimum of one Elasticsearch node, one natlas server and one natlas agent, with that deployment order. The server controls agent orchestration and scan configuration and provides search and browse over the data in Elastic, while the agent fetches work and performs the scans.

### How is natlas deployed?

Docker only, since June 15, 2020, with published images for the server and the agent on Docker Hub. The quickest arrangement is to run the Elasticsearch node, the server and the agent containers on the same server.

### What storage does natlas use?

Elasticsearch holds the search and browse layer for the collected scan data, and the development compose file also runs MinIO as an S3 compatible store, PostgreSQL for application state, and an OpenTelemetry collector for telemetry.

### What licence is natlas released under?

Apache 2.0, with copyright 0xdade for 2020 and Intel Corporation for 2016 to 2018. The README also notes that the platform uses other open source projects with their own licences and directs licence questions to those projects.

## Sources

- [Issues](https://github.com/natlas/natlas/issues)
- [License: Apache-2.0](https://github.com/natlas/natlas/blob/main/LICENSE)
- [natlas/natlas on GitHub](https://github.com/natlas/natlas)
- [README](https://github.com/natlas/natlas/blob/main/README.md)
- [Releases](https://github.com/natlas/natlas/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/natlas-natlas