Feluda

🔎 Feluda is a Rust-based command-line tool that analyzes the dependencies of a project, notes down their licenses, and flags any permissions that restrict personal or commercial usage or are incompatible with your project's license.

👋 It's still highly experimental, but fast iterating. Welcoming contributors and support to help bring out this project even better!

Installation

Official Distribution 🎉:

Rust (Crate)

Prerequisites

• Rust installed on your system.

If you already had it, make sure it's up-to-date and update if needed. (Optional) Set rust path if not set already.

Install

cargo install feluda

DEB Package (Debian/Ubuntu/Pop! OS)

Feluda is available as a DEB package for Debian-based systems.

1. Download the latest .deb file from GitHub Releases
2. Install the package:

# Install the downloaded DEB package
sudo dpkg -i feluda_*.deb

# If there are dependency issues, fix them
sudo apt install -f

RPM Package (RHEL/Fedora/CentOS)

Feluda is available as an RPM package for Red Hat-based systems.

1. Download the latest .rpm file from GitHub Releases
2. Install the package:

# Install the downloaded RPM package
sudo rpm -ivh feluda_*.rpm

# Or using dnf (Fedora/newer RHEL)
sudo dnf install feluda_*.rpm

# Or using yum (older RHEL/CentOS)
sudo yum install feluda_*.rpm

Community Maintained 🙌:

Homebrew (maintained by @chenrui333)

feluda is available in the Homebrew. You can install it using brew:

brew install feluda

Arch Linux (maintained by @adamperkowski)

feluda is available in the AUR. You can install it using an AUR helper (e.g. paru):

paru -S feluda

NetBSD (maintained by @0323pin)

On NetBSD a package is available from the official repositories. To install it, simply run:

pkgin install feluda

Package Managers 📦:

Track releases on github releases or via release feed.

Build from Source (advanced users)

Note: This might have experimental features which might not work as intended.

Clone and Build

First, clone the repository:

git clone https://github.com/anistark/feluda.git
cd feluda

Then, build the project using Cargo:

cargo build --release

Finally, to make feluda available globally, move the binary to a directory in your PATH. For example:

sudo mv target/release/feluda /usr/local/bin/

Usage

Feluda provides license analysis by default, with an additional command for generating compliance files. Analyze your project's dependencies and their licenses:

# Basic usage
feluda

# Specify a path to your project directory
feluda --path /path/to/project/

# Check with specific language
feluda --language {rust|node|go|python|java|maven|gradle|c|cpp|r|ruby}

# Skip local file checks and force network lookup only
feluda --no-local

# Filter by OSI approval status
feluda --osi approved        # Show only OSI approved licenses
feluda --osi not-approved   # Show only non-OSI approved licenses
feluda --osi unknown        # Show licenses with unknown OSI status

Local License Detection

By default, Feluda checks local files first for license information before making network requests: - Node.js: Checks LICENSE files in local node_modules (npm, pnpm, yarn, bun) - Rust: Checks Cargo.toml manifests for license field - Java: Fetches POM files from Maven Central to extract <licenses> metadata

Use --no-local to skip local checks and force network-only license lookup.

License File Generation

Generate compliance files for legal requirements:

# Interactive file generation
feluda generate

# Generate for specific language and license
feluda generate --language rust --project-license MIT

# Generate for specific path
feluda generate --path /path/to/project/

SBOM Generation

Generate Software Bill of Materials (SBOM) for your project:

# Generate all supported SBOM formats (SPDX + CycloneDX)
feluda sbom

# Generate SPDX format SBOM only
feluda sbom spdx

# Generate SPDX format SBOM to file
feluda sbom spdx --output sbom.json

# Generate CycloneDX format SBOM only
feluda sbom cyclonedx

# Generate CycloneDX format SBOM to file
feluda sbom cyclonedx --output sbom.json

# Generate all formats with custom output
feluda sbom --output sbom-output

Supported SBOM Formats: - SPDX 2.3 - Software Package Data Exchange format (JSON) - CycloneDX - CycloneDX v1.5 format (JSON)

What's Included in SBOM: - Package names and versions - License information - SPDX identifiers - License compatibility flags - Tool metadata and generation timestamp

Use Cases: - 🔒 Security compliance - Track all dependencies for vulnerability management - 📋 Supply chain transparency - Document your software's components - 🏢 Enterprise requirements - Meet organizational SBOM mandates - 🔍 Audit preparation - Provide comprehensive dependency documentation

SBOM Validation

Validate SBOM files to ensure they conform to the SPDX or CycloneDX specifications:

# Validate an SBOM file
feluda sbom validate spdx.json

# Validate and save the report to a file
feluda sbom validate spdx.json --output validation-report.txt

# Validate and output report in JSON format
feluda sbom validate spdx.json --json

# Validate and save JSON report to file
feluda sbom validate spdx.json --json --output validation-report.json

Cache Management

Feluda caches GitHub license data to improve performance on repeated runs:

# View cache status (size, age, health)
feluda cache

# Clear the cache
feluda cache --clear

How Caching Works: - Cache is stored at .feluda/cache/github_licenses.json - 30-day automatic expiration (cache is refreshed if older) - Only licenses successfully fetched from GitHub API are cached - Cache is automatically loaded on subsequent analysis runs - Reduces GitHub API calls and improves analysis speed

Watch Mode

Continuously re-scan your project whenever a dependency file changes. Feluda watches the project tree for filesystem events and re-runs the license check automatically — handy while adding or upgrading dependencies, especially with AI coding tools that pull in packages on the fly.

# Watch the current directory and re-scan on dependency changes
feluda watch

# Watch a specific path
feluda watch --path /path/to/project/

# Adjust the debounce window (ms to wait after a change before re-scanning)
feluda watch --debounce 800

Watch mode reuses the same flags as a normal scan — pass them before the watch subcommand:

# Watch and report only restrictive licenses, as JSON
feluda --restrictive --json watch

# Watch in strict mode against a specific project license
feluda --strict --project-license MIT watch

What it watches: every dependency manifest and lockfile Feluda understands (Cargo.toml/Cargo.lock, package.json/package-lock.json/yarn.lock/pnpm-lock.yaml, go.mod/go.sum, pyproject.toml/requirements.txt/uv.lock, pom.xml/build.gradle, *.csproj, and more), discovered recursively while honouring .gitignore and skipping vendored directories like node_modules/ and target/.

Note: Watch mode is report-only — it does not support the interactive TUI (--gui) or remote repositories (--repo). Press Ctrl-C to stop.

Scheduled & looped scanning

When a long-running watcher isn't a good fit (CI, network filesystems, periodic audits), run Feluda's single-shot scan on a timer instead. Add --fail-on-restrictive (or --fail-on-incompatible) so the exit code gates your pipeline:

# cron — scan every 30 minutes and fail if a restrictive license appears
*/30 * * * * cd /path/to/project && feluda --fail-on-restrictive

# Claude Code /loop — re-run the check every 30 minutes
/loop 30m feluda --restrictive

# CI gate — non-zero exit stops the build
feluda --fail-on-restrictive --json

GitHub API Authentication

Feluda uses the GitHub API to fetch license information. Unauthenticated requests are limited to 60 requests/hour, which may be insufficient for large projects or frequent scans.

Increase rate limits by providing a GitHub personal access token:

# Via command-line flag
feluda --github-token <your_token>

# Or via environment variable (recommended for CI/CD)
export GITHUB_TOKEN=<your_token>
feluda

Authenticated requests get 5,000 requests/hour. No special scopes are required for the token—public repository access is sufficient.

Run feluda on a github repo directly

feluda --repo <repository_url> [--ssh-key <key_path>] [--ssh-passphrase <passphrase>] [--token <https_token>]

<repository_url>: The URL of the Git repository to clone (e.g., git@github.com:user/repo.git or https://github.com/user/repo.git).

--ssh-key <key_path>: (Optional) Path to a private SSH key for authentication.

--ssh-passphrase <passphrase>: (Optional) Passphrase for the SSH key.

--token <https_token>: (Optional) HTTPS token for authenticating with private repositories.

---

If you're using Feluda, feel free to grab a Scanned with Feluda badge for your project:

[![Scanned with Feluda](https://img.shields.io/badge/Scanned%20with-Feluda-brightgreen)](https://github.com/anistark/feluda)

Replace the repo name and username. Once you've the Feluda GitHub Action setup, this badge will be automatically updated.

License Compliance Files

Feluda can generate essential compliance files required for commercial software distribution and open source projects.

NOTICE File

A NOTICE file is a concise summary document that provides attribution for third-party components:

• Purpose: Quick overview of all third-party components and their licenses
• Content: Organized by license type, lists all dependencies with their versions
• Use Cases:
• Legal compliance documentation
• Quick reference for license audits
• Attribution requirements for many open source licenses

THIRD_PARTY_LICENSES File

A THIRD_PARTY_LICENSES file provides comprehensive license documentation:

• Purpose: Complete legal documentation for all dependencies
• Content: Full license texts, compatibility analysis, package URLs, and copyright information
• Use Cases:
• Commercial software distribution requirements
• Legal compliance for enterprise applications
• Due diligence for acquisitions and audits
• App store submissions (iOS, Android, etc.)

Why These Files Are Important

Legal Protection: Many open source licenses require attribution when redistributing code. These files ensure compliance and protect your organization from legal issues.

Transparency: Shows