Metadata-Version: 2.2
Name: loci-service-asmslicer
Version: 1.0.17
Summary: LOCI static analysis service
Requires-Python: >=3.12
Requires-Dist: angr>=9.2.223
Requires-Dist: beautifultable>=1.1.0
Requires-Dist: boto3>=1.40.60
Requires-Dist: capstone>=5.0.3
Requires-Dist: cxxfilt>=0.3.0
Requires-Dist: levenshtein>=0.27.3
Requires-Dist: lief>=0.17.1
Requires-Dist: lxml>=6.0.2
Requires-Dist: networkx>=3.5
Requires-Dist: pandas>=2.3.3
Requires-Dist: pydot>=3.0.4
Requires-Dist: pyelftools>=0.32
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: s3fs>=2025.10.0
Requires-Dist: smart-open[s3]>=7.5.0
Requires-Dist: xxhash>=3.6.0
Description-Content-Type: text/markdown

# asmslicer

asmslicer is the **LOCI static-analysis service**. It slices ELF binaries (embedded firmware and executables) into:

* ASM basic blocks and linear execution segments, including CFG info.
* Callgraph between functions.
* Symbol and variable-access information.

and additionally provides binary diffing, worst-case stack-depth estimation, ROM/RAM memory-usage reports, and cross-artifact symbol dependency resolution.

## Documentation

Full documentation lives in [`docs/`](docs/01-overview.md) — start with the [overview](docs/01-overview.md).

| | |
|---|---|
| [1. Overview and scope](docs/01-overview.md) | What the service does; scope boundary vs. the TDMP trace pipeline |
| [2. Architecture](docs/02-architecture.md) | Processing pipeline, disassembly engines, data flow |
| [3. CLI reference](docs/03-cli.md) | Subcommands `slice`, `diff`, `stack-depth`, `memmap`, `deps`; exit codes |
| [4. Output formats](docs/04-output.md) | Normative schemas of all CSV/DOT/JSON artifacts |
| [5. Analyses](docs/05-analyses.md) | Methods, assumptions, guarantees, blind spots |
| [6. Platform support](docs/06-platforms.md) | aarch64 / Cortex-M / TriCore support matrix |
| [7. Deployment and operations](docs/07-deployment.md) | Docker image, env vars, security posture |
| [8. Dependencies](docs/08-dependencies.md) | Third-party inventory and licenses |
| [9. Quality assurance](docs/09-qa.md) | Test suites and golden-data regression evidence |
| [10. Limitations and determinism](docs/10-limitations.md) | Soundness limits, reproducibility statement |
| [11. Release and versioning](docs/11-versioning.md) | CI/CD, image tagging, provenance |

## How do I get set up?

* asmslicer uses [uv](https://docs.astral.sh/uv/) for Python project and dependency management; install uv first.

### External dependencies

The following system tools are required for full functionality:
* `binutils` — provides `c++filt` for C++ symbol demangling
* `llvm-18` — provides `llvm-ifs-18` for interface stub generation
* `rustfilt` — for Rust symbol demangling

On Debian/Ubuntu:
```
sudo apt-get update && sudo apt-get install binutils rustfilt
wget -qO- https://apt.llvm.org/llvm.sh | sudo bash -s -- 18
```

For CUDA binary analysis (optional):
```
# Requires NVIDIA CUDA toolkit
sudo apt-get install cuda-cuxxfilt-13-0 cuda-cuobjdump-13-0 cuda-nvdisasm-13-0
```

* Then configure the venv using uv:
```
uv venv
source .venv/bin/activate
uv sync
```
* Once the venv is set up you can run the service CLI locally:
```
loci-service-asmslicer --help
loci-service-asmslicer slice path/to/app.elf ./out
```
* The Docker container image can also be built in the standard way:
```
docker build -t loci-platform/loci-service-static-analysis .
```

## Contribution guidelines

* The project uses the `main` branch for active development.
* Changes are merged by creating a pull request targeting `main`.
* Merging to `main` automatically triggers a build pipeline which deploys the Docker container to AWS ECR with the `latest` tag.
* Creating an annotated tag with an `x.y.z` version number triggers a pipeline build which deploys the Docker container to AWS ECR with the `x.y.z` tag. See [docs/11-versioning.md](docs/11-versioning.md).

## Who do I talk to?

* Repo owner or admin.
