# Getting started

> Install the Nightshade v0.1.1 release, scan the shipped example, then scan your own Compact contracts and read the result.

Canonical: https://nightshade.dicksonwu.xyz/getting-started.html
Release: Nightshade 0.1.1 (v0.1.1)

## Install the release

The release package targets Linux x86-64/glibc with Node 22 or 24 and libstdc++ providing `GLIBCXX_3.4.31` or newer (Ubuntu 24.04 or Debian 13). You also need curl and npm. Use an empty directory so installation stays separate from your project.

```sh
curl -fL https://github.com/DicksonWu654/nightshade/releases/download/v0.1.1/nightshade-compact-0.1.1.tgz -o nightshade-compact-0.1.1.tgz
npm install --prefix ./.nightshade --no-audit --no-fund ./nightshade-compact-0.1.1.tgz
./.nightshade/node_modules/.bin/nightshade ./.nightshade/node_modules/nightshade-compact/examples/review/contract.compact --fail-on high
```

This scans the positive example shipped in the tarball. It prints a medium `ledger-bound-preimage-publication` finding and exits successfully because the failure threshold is high. Installation downloads dependencies; normal scans do not need network access.

Scan the corrected example next:

```sh
./.nightshade/node_modules/.bin/nightshade ./.nightshade/node_modules/nightshade-compact/examples/review/corrected.compact
```

Expect no findings and complete analysis. That is a control for this rule, not a security certification.

## Scan your application

Replace the example path with your contract or project directory. These commands assume you are still in the install directory:

```sh
./.nightshade/node_modules/.bin/nightshade /path/to/contracts --compiler-version 0.34.0 --fail-on medium
./.nightshade/node_modules/.bin/nightshade /path/to/contracts --compiler-version 0.34.0 --json
./.nightshade/node_modules/.bin/nightshade /path/to/contracts --compiler-version 0.34.0 --sarif > report.sarif
```

Choose the compiler profile your application actually uses. Normal scans neither run a compiler nor establish compiler acceptance. Install application imports locally first. Add dependency directories with `--compact-path`; multiple directories use the platform path delimiter. `COMPACT_PATH` is also supported.

Directory scans discover application roots and skip dependency, generated and cache directories. Imported code is still analyzed. A directory containing only libraries is incomplete; choose a root exporting the circuits you want to review. Use configured roots for a stable application selection.

## Read the result

| Exit code | Default coverage policy |
| --- | --- |
| 0 | Complete analysis; no unsuppressed new finding meets the threshold |
| 1 | Complete analysis; a finding meets the threshold |
| 2 | Incomplete or invalid analysis, configuration error or worker failure |

Check diagnostics, `status`, `coverage.baselineStatus` and `coverage.rules`. A quiet result with missing coverage needs investigation. `--fail-on none` does not clear incomplete analysis. An explicit rule-warning policy can permit only rule-scoped gaps while preserving incomplete status; see [configuration](https://nightshade.dicksonwu.xyz/configuration.md).

## Other installation routes

For a source checkout, the prerequisites are Linux x86-64/glibc, Node 22 or 24, npm, Git, Python, make and a C/C++ compiler. From that checkout:

```sh
npm ci
npm run build
npm run demo
```

The demo verifies the shipped positive and corrected control. Installation and build download pinned dependencies and build tools.

For macOS, use the Linux Docker image from a source checkout:

```sh
docker build --platform linux/amd64 -t nightshade:local .
docker run --platform linux/amd64 --rm --network none -v "$PWD:/project:ro" nightshade:local examples/review/contract.compact
```

The positive example returns a finding status. Mount application imports alongside sources. Other native targets need separate build qualification.

[Release](https://github.com/DicksonWu654/nightshade/releases/tag/v0.1.1) | [Full user guide](https://github.com/DicksonWu654/nightshade/blob/v0.1.1/docs/user-guide.md) | [Compiler profiles](https://github.com/DicksonWu654/nightshade/blob/v0.1.1/docs/compiler-onboarding.md#supported-profiles) | [CI setup](https://nightshade.dicksonwu.xyz/github-action.md)