Getting started

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.

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:

./.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:

./.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#

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.

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:

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:

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.