README
¶
repyy
Scan an unfamiliar repository before installing its dependencies or running its
code. repyy is a local, read-only malware and supply-chain scanner for source
you do not fully trust. It reads files as data and does not import, build, test,
or execute the target.
Quick start
Install a release from GitHub Releases, or use one of the package-manager commands below:
# macOS
brew install --cask Kevin-Umali/tap/repyy
# Windows PowerShell
scoop bucket add repyy https://github.com/Kevin-Umali/scoop-bucket
scoop install repyy/repyy
# Any platform with Go
go install github.com/Kevin-Umali/repyy/cmd/repyy@latest
Scan a local checkout and save a reviewable report:
repyy version
repyy scan ./unfamiliar-repository --format html --output repyy-report.html
Open repyy-report.html locally. The report is self-contained and makes no
network requests while it is displayed; a source link can open the provider
website when clicked. Treat reports as sensitive review data.
NO FINDINGS means no enabled rule matched in completed coverage. It does not
prove that a repository is safe. Treat SCAN INCOMPLETE as unresolved and
review its warnings before relying on the result.
Documentation
Open the checked-in documentation site locally for the guided web experience (preview instructions):
- Install and run a first scan
- CLI commands and flags
- Trusted configuration
- Docker and manual VM isolation
- Detection coverage and limits
- Offline intelligence and updates
- AI agent skill workflow
The same topics are available as detailed Markdown guides for repository readers: installation, CLI, configuration, Docker sandbox, manual VM workflows, and coverage.
The optional AI agent skill teaches compatible agents to scan before execution and to report incomplete coverage. Install it with:
npx skills add Kevin-Umali/repyy --skill repyy
This optional installer needs Node/npm, Git, and network access. The skill
contains instructions; install the repyy CLI separately. See the
web skill guide for the full workflow.
Contributing
git clone https://github.com/Kevin-Umali/repyy.git
cd repyy
make check
make security
Read CONTRIBUTING.md before changing detections, output, network behavior, or report compatibility. See SECURITY.md for private vulnerability reports.
License
MIT. Third-party intelligence sources are listed in NOTICE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
repyy
command
|
|
|
repyy-intelgen
command
repyy-intelgen refreshes metadata for the curated embedded advisory set.
|
repyy-intelgen refreshes metadata for the curated embedded advisory set. |
|
internal
|
|
|
app
Package app implements repyy's command-line orchestration and exit policy.
|
Package app implements repyy's command-line orchestration and exit policy. |
|
config
Package config loads explicit, trusted rules and suppressions.
|
Package config loads explicit, trusted rules and suppressions. |
|
intel
Package intel contains the dated, offline threat-intelligence snapshot.
|
Package intel contains the dated, offline threat-intelligence snapshot. |
|
manifest
Package manifest extracts dependency declarations without executing package managers.
|
Package manifest extracts dependency declarations without executing package managers. |
|
model
Package model defines repyy's stable report-domain types.
|
Package model defines repyy's stable report-domain types. |
|
output
Package output renders scan reports without exposing unredacted source data.
|
Package output renders scan reports without exposing unredacted source data. |
|
sandbox
Package sandbox runs scans in a narrowly configured Docker container.
|
Package sandbox runs scans in a narrowly configured Docker container. |
|
scan
Package scan performs bounded, non-executing static repository inspection.
|
Package scan performs bounded, non-executing static repository inspection. |
|
scan/media
Package media inspects files that carry active content in media formats.
|
Package media inspects files that carry active content in media formats. |
|
scan/supplychain
Package supplychain inspects package manifests, build configuration, and package-manager wrappers without resolving or executing dependencies.
|
Package supplychain inspects package manifests, build configuration, and package-manager wrappers without resolving or executing dependencies. |
|
scan/workflow
Package workflow detects risky GitHub Actions workflow structures.
|
Package workflow detects risky GitHub Actions workflow structures. |
|
source
Package source safely prepares local and remote repositories for inspection.
|
Package source safely prepares local and remote repositories for inspection. |