Metadata-Version: 2.4
Name: picuscan
Version: 1.0.0rc1
Summary: A unified orchestration and enrichment layer for C/C++ static analysis tools
Author: AISEC Code Audit Team
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Security
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: attrs>=25.2.0
Requires-Dist: cattrs>=25.1.0
Requires-Dist: click>=8.0.3
Requires-Dist: neo4j>=6.0.1
Requires-Dist: networkx>=3.0
Requires-Dist: tqdm>=4.68.4
Requires-Dist: xmltodict>=1.0.0
Requires-Dist: pandas>=2.0.3
Requires-Dist: tabulate>=0.9.0
Maintainer: Tobias Specht, Hannah Schmid
Maintainer-email: Tobias Specht <tobias.specht@aisec.fraunhofer.de>, Hannah Schmid <hannah.schmid@aisec.fraunhofer.de>
Requires-Python: >=3.11, <3.15
Project-URL: Documentation, https://github.com/Fraunhofer-AISEC/picuscan
Project-URL: Repository, https://github.com/Fraunhofer-AISEC/picuscan
Project-URL: Bug Tracker, https://github.com/Fraunhofer-AISEC/picuscan/issues
Description-Content-Type: text/markdown

﻿<!--
SPDX-FileCopyrightText: 2026 AISEC Code Audit Team

SPDX-License-Identifier: CC0-1.0
-->

# Picuscan

Picuscan (Picus: Latin for woodpecker; a scanner hunting for bugs in source code) is an orchestration and utility tool for C/C++ security code audits. It provides a unified interface for running multiple external static analysis (SAST) tools, aggregates and normalizes their findings, and enriches the results with security metadata such as CWE categories.

Picuscan does not perform static analysis itself; instead, it collects tool outputs and turns them into a single, audit-focused view. It also ranks findings using a heuristic that combines tool feedback with practical experience to help auditors prioritize likely true positives. Additional utilities support audit preparation, including generating compilation databases, preparing source code, and working with SARIF files.

## Quick Start

### Docker (Recommended)

```bash
$ docker pull ghcr.io/fraunhofer-aisec/picuscan:main
$ docker run --rm -it -v $PWD:$PWD:z -w $PWD --entrypoint bash ghcr.io/fraunhofer-aisec/picuscan:main
$ picuscan --help
```

See [Installation → Docker](docs/installation.md#docker) for more details.

### From PyPI

```bash
$ pipx install picuscan
$ picuscan --help
```

**Note:** When installing via pip, you must install the analysis tools separately. See [Installation → Dependencies](docs/installation.md#dependencies) for a list of supported tools.

## Usage

You need a [compilation database][compdb] for the analysis to work.
Run analysis and generate a SARIF report:

```bash
$ picuscan analyze
```

See [Usage](docs/usage.md) for comprehensive documentation.

## Documentation

- [Installation](docs/installation.md) - Docker and pip installation
- [Usage](docs/usage.md) - Analysis, compilation databases, preprocessing
- [Analyzers](docs/analyzers.md) - Tool-specific options and configurations

## License

[Apache-2.0](LICENSE)

## Acknowledgments

This work was partly funded by the German Federal Ministry of Economic Affairs and Energy (BMWE) as part of the ATLAS-L4 project (grant no. 19A21048D).
This work was partly funded by the German Federal Ministry of Education and Research (BMBF) as part of the SHIQ project (grant no. 16KIS1955).

[compdb]: https://clang.llvm.org/docs/JSONCompilationDatabase.html