# cscan: A Distributed Enterprise Network Asset Scanner Built on Go and Vue3

> cscan is a self-hosted, distributed security scanning platform for enterprise network asset management, combining port and subdomain discovery, 41,537 fingerprint rules, and a mirrored Nuclei PoC library in a single Docker Compose deployment. It is actively developed, with the last push on 2026-09-06.

**tangxiaofeng7/cscan** — A distributed security and vulnerability scanner built on Go and Vue3 for enterprise environments, covering port and subdomain discovery, fingerprinting, and PoC verification workflows.

- Repository: https://github.com/tangxiaofeng7/cscan
- Website: http://cscan.txf7.cn:8080
- Stars: 434 · Forks: 64
- Language: Go
- License: MIT
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/tangxiaofeng7-cscan

## What cscan Solves and Who It Is For

Enterprise security teams managing large IP ranges face a common problem: asset discovery, technology fingerprinting, and vulnerability verification are handled by separate tools that do not share data or coordinate work across multiple machines. cscan addresses this by providing a single web-based platform where all three workflows, port and subdomain scanning, fingerprint matching, and PoC execution, run inside one system with a shared task queue.

The platform targets enterprise environments specifically. The architecture includes multiple Worker nodes that accept scan jobs from a central API, a priority queue, task sharding, scheduled tasks, and reconnection recovery after a dropped connection. These features matter when scan targets number in the hundreds or thousands and scans need to run continuously rather than on demand. Security engineers who already run ProjectDiscovery tools but want a coordinated dashboard and asset database are the primary audience. The README also covers notification subscriptions and a node monitoring panel, which gives operators visibility into worker health without leaving the web interface.

## Architecture: Go Backend, Vue3 Frontend, MongoDB, and Redis

The backend is written in Go using the go-zero framework. Scan jobs flow through Redis, which acts as the distributed queue between the API server and Worker nodes. MongoDB stores the asset records, scan history, fingerprint matches, and vulnerability data. The frontend is a Vue3 application served alongside the API.

The go.mod file confirms the dependencies: github.com/zeromicro/go-zero for the service framework, github.com/redis/go-redis/v9 for queue communication, go.mongodb.org/mongo-driver for asset storage, and github.com/projectdiscovery/wappalyzergo for one component of the fingerprint library. The worker node directory is separate from the API, which means you can run multiple workers on different machines while they all report to the same API and queue.

The docker-compose.yaml file makes MongoDB and Redis internal to the cscan_network and does not publish their ports externally. The API port remains externally reachable. This network topology means the database layer is not exposed by default, though the README notes that the API port still requires external access controls.

## Deploying cscan with Docker Compose

The README documents a zero-configuration path that uses bundled default credentials, intended only for evaluation. The full startup sequence is:

```bash
git clone https://github.com/tangxiaofeng7/cscan.git
cd cscan
cp .env.example .env
docker compose up -d
```

After the containers start, the web interface is available at https://ip:7777. The .env.example file contains five required fields: a JWT signing secret, MongoDB admin username and password, Redis password, and a Worker registration key. The file's comments explain that the MongoDB password is applied at first volume creation and that changing it later affects existing data.

To generate strong values for each credential, the .env.example comments suggest:

```bash
openssl rand -hex 32
```

Run that command once for each secret and paste the output into .env before starting the stack in a production environment. To pull updated images later:

```bash
docker compose pull && docker compose up -d
```

For local development, the repository includes platform-specific scripts. On macOS and Linux, run:

```bash
./dev.sh
```

On Windows PowerShell, the equivalent is ./dev.ps1. These scripts set up a local development environment with hot reload.

## Fingerprint Library and Nuclei PoC Integration

The platform bundles 41,537 fingerprint rules. This count includes 7,523 Wappalyzer application fingerprints and 34,014 custom rules. The README notes that the actual count varies depending on when the Docker image was built and how many custom templates have been added since. The fingerprint library supports extension, so teams can add their own rules for internal software.

The PoC library mirrors the upstream Nuclei Templates repository from ProjectDiscovery and reflects the count in TEMPLATES-STATS.json at build time, documented at 13,412 entries at the time of writing. Because this is a mirror rather than a fork, the PoC count changes each time the Docker image is rebuilt against a newer upstream snapshot. Teams that need a pinned PoC set would need to control the build process themselves.

The integration with Nuclei Templates is a practical shortcut for keeping vulnerability coverage up to date without writing custom detectors, but it creates a dependency on the upstream project's pace and quality. Any false positives or accuracy issues in the upstream templates propagate into cscan's verification workflow. The README also notes that custom PoC packs can be downloaded separately from the project's own upload endpoint, giving teams the option to extend beyond the Nuclei mirror.

## The leased-task-v1 Upgrade Constraint

The README documents a non-trivial operational constraint when upgrading to the leased-task-v1 worker protocol. This protocol applies to workers that connect directly to Redis rather than through the API. Before enabling it, all old workers must be stopped and any in-flight tasks must drain completely. Only after the queue is empty should the API and all workers be upgraded together.

The README explicitly warns against rolling the upgrade: mixing old direct-Redis workers with a new leased-task-v1 deployment is unsupported. Old execution records that lack an instanceId or lease token are rejected safely rather than silently accepted. The design choice prioritizes correctness over backward compatibility, which means a failed partial upgrade leaves some tasks unrecoverable rather than producing subtly wrong results.

This constraint matters for teams that run cscan continuously against large asset sets. Planning a maintenance window specifically to drain the task queue before upgrading is not optional. Teams accustomed to rolling deploys of other Go services need to treat this upgrade differently.

## Comparison with ProjectDiscovery Nuclei

ProjectDiscovery's Nuclei is the closest single-tool alternative for PoC-based vulnerability scanning. Nuclei runs as a CLI tool on a single machine, uses the same template set that cscan mirrors, and is well-documented for one-off and scheduled scans. The key difference is that Nuclei is a scanner without an asset management layer: it does not maintain a persistent database of discovered hosts, port states, fingerprint history, or scan timelines across multiple runs.

cscan wraps the Nuclei template library inside a platform that tracks all of that context. An engineer who wants to know which of their 2,000 internal hosts matched a new CVE template last Tuesday can query that in cscan's asset database; they cannot do the same with a plain Nuclei install without building their own storage layer. The trade-off is operational complexity: cscan requires Docker, MongoDB, and Redis, while Nuclei is a single binary.

For teams that already have data pipelines and just need a scanner, Nuclei alone is simpler. For teams that need coordinated, tracked scanning across many workers, cscan provides that coordination without custom glue code.

## Conclusion

cscan suits security teams that need a unified, self-hosted platform to manage asset discovery, fingerprinting, and PoC verification across a distributed workforce. It is not suited for single-machine quick scans or teams unfamiliar with Docker and Go environments. Before deploying to production, replace every default credential in .env.example with strong random values, and review the leased-task-v1 upgrade notes carefully if you run multiple workers connected through Redis.

## FAQ

### Does cscan support running multiple scanner workers on separate machines?

Yes. The architecture separates the API server from Worker nodes, and workers register with the API using the CSCAN_WORKER_KEY credential from .env. Multiple workers can run on different machines and pull jobs from the shared Redis queue, with priority queuing and task sharding built in.

### What databases does cscan use and are they exposed externally by default?

cscan uses MongoDB for asset storage and Redis as the task queue. The docker-compose.yaml configuration places both on an internal cscan_network and does not publish their ports to the host. Only the API port is externally reachable, though the README notes it still requires external access controls.

### How does cscan keep its PoC library current?

cscan mirrors the Nuclei Templates repository from ProjectDiscovery and reflects the template count at Docker image build time. The count changes when the image is rebuilt against a newer upstream snapshot. Teams that need a pinned PoC set need to control the image build process themselves.

## Sources

- [Official documentation](http://cscan.txf7.cn:8080)
- [Official README](https://github.com/tangxiaofeng7/cscan#readme)
- [Project repository](https://github.com/tangxiaofeng7/cscan)

---

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