SolidityScan

Secure your Solidity smart contracts straight from your terminal or JavaScript code! SolidityScan is a lightweight CLI and Node.js library that connects to the CredShields SolidityScan API to identify vulnerabilities, gas optimisations, and other issues in your smart-contract projects.

Table of Contents

1. Features
2. Installation
3. Getting an API Key
4. CLI Usage
   • Scan a local directory
   • Run a local file server
5. Programmatic Usage
6. Examples
7. Contributing
8. License

Features

• 📦 Local Directory Scanning – Zip and upload your local Solidity source code and get instant feedback in the terminal. • ⚡ Real-time Progress – Live WebSocket updates with an elegant spinner so you always know the scan status. • 📋 Readable Reports – Vulnerabilities and severities are displayed in coloured, column-aligned tables, followed by a concise scan summary. • 🌐 Local WebSocket File Server – Spin up a file server for quick web-UI integrations and demos.

Installation

# Install globally to use the `solidityscan` CLI
yarn global add solidityscan        # or npm install -g solidityscan

# Add to a project for programmatic use
npm install solidityscan --save     # or yarn add solidityscan

Requirement: Node.js >= 14

Getting an API Key

1. Sign up or log in at solidityscan.com.
2. Navigate to API Keys and generate a new key.
3. Either export it as an environment variable:

export SOLIDITYSCAN_API_KEY="YOUR_API_KEY"

…or pass it as the last argument in each CLI command (see below).

CLI Usage

After installing globally you will have a solidityscan binary in your PATH. Run solidityscan --help to view the brief usage guide.

Scan a Local Directory

Analyse a local folder containing .sol files. The tool packages the Solidity source, uploads it, waits for the scan to finish and prints the results.

If using with API key in terminal command.

solidityscan local /path/to/my/contracts [api-key] [project-name]

If using with API key in environment variable.

solidityscan local /path/to/my/contracts [project-name]

If no project name is provided, it will default to "LocalScan".

Run a Local File Server

Start a WebSocket file server to expose your local directory to the SolidityScan web-UI A unique identifier (`--id`) is mandatory – this becomes the sub-domain of the temporary public URL.

# Serve current directory on default port 9462 (or 9463-9466 if 9462 is busy)
solidityscan -l --id <id-from-solidityscan>

# Serve a specific directory
solidityscan -l -p /my/contracts --id <id-from-solidityscan>

# Bind to an explicit port instead of the automatic range
solidityscan -l -p ./src --id <id-from-solidityscan> --port 9000

Behaviour notes:

• If --port is omitted the CLI tries to bind to 9462 and, if in use, increments the port up to 5 times (9462-9466).
• The identifier should be exactly the string shown on SolidityScan's Connect to Localhost page – copy it from the web-UI and use it with --id.

Programmatic Usage

You can also integrate SolidityScan directly into your Node.js scripts or CI pipelines:

const solidityscan = require("solidityscan");

(async () => {
  const apiToken = process.env.SOLIDITYSCAN_API_KEY;

  // Scan a local directory (same behaviour as CLI `test`)
  await solidityscan.runTests("./contracts", apiToken);
})();

Available exported helpers:

• runTests(directoryPath, apiToken)
• scan() – executes the CLI with current process.argv (internally used by the binary).

Examples

You can find full working examples inside the examples/ directory (coming soon).

Contributing

1. Fork the repo and create your feature branch: git checkout -b feat/awesome-feature.
2. Install dependencies: npm install.
3. Run the tests: npm test.
4. Commit your changes and push: git push origin feat/awesome-feature.
5. Open a pull request – we love to review!

Please adhere to the existing code style and add unit tests for any new logic.

License

This project is licensed under the ISC license – see the LICENSE file for details.