Skip to content

Commit ef464d5

Browse files
kirankotarikirankotari
committed
docs: rewrite README for multi-repo structure
1 parent 2b4a4a5 commit ef464d5

1 file changed

Lines changed: 24 additions & 160 deletions

File tree

‎README.md‎

Lines changed: 24 additions & 160 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,15 @@
1-
# OSSGuard
1+
# OSSGuard — Python Implementation
22

3-
**One CLI to guard any OSS project with OpenSSF security best practices — bootstrap, scan, and monitor.**
3+
**The reference Python implementation of [OSSGuard](https://github.com/kirankotari/ossguard).**
44

5-
[![CI](https://github.com/kirankotari/ossguard/actions/workflows/ci.yml/badge.svg)](https://github.com/kirankotari/ossguard/actions/workflows/ci.yml)
5+
[![CI](https://github.com/kirankotari/ossguard-python/actions/workflows/ci.yml/badge.svg)](https://github.com/kirankotari/ossguard-python/actions/workflows/ci.yml)
66
[![PyPI](https://img.shields.io/pypi/v/ossguard)](https://pypi.org/project/ossguard/)
7-
[![Docker](https://ghcr-badge.egpl.dev/kirankotari/ossguard/latest_tag?trim=major&label=docker)](https://github.com/kirankotari/ossguard/pkgs/container/ossguard)
87
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
98
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
109

11-
> *OSSGuard implements OpenSSF best practices and is intended for future contribution to the OpenSSF community.*
10+
> For full documentation, all install methods, and command examples, see the main [ossguard](https://github.com/kirankotari/ossguard) repo.
1211
13-
---
14-
15-
## The Problem
16-
17-
The [OpenSSF](https://openssf.org/) ecosystem has 30+ excellent tools, frameworks, and guides for securing open source software — Scorecard, Sigstore, SLSA, SBOM, CodeQL, Dependabot, and more.
18-
19-
But setting them all up manually takes **hours**. And once set up, there's no unified way to monitor dependency health, track compliance, or assess supply-chain risk.
20-
21-
**OSSGuard** solves this with **26 commands** covering the full security lifecycle:
22-
23-
1. **Bootstrap** — set up all OpenSSF security configurations in one command
24-
2. **Analyze** — audit security posture, dependencies, vulnerabilities, and compliance
25-
3. **Remediate** — auto-fix issues, generate reports, and enforce policies
26-
27-
## Installation
28-
29-
### PyPI (recommended)
12+
## Install
3013

3114
```bash
3215
pip install ossguard
@@ -35,161 +18,42 @@ pip install ossguard
3518
pipx install ossguard
3619
```
3720

38-
### Standalone Binaries (no Python required)
39-
40-
Download pre-built binaries from [GitHub Releases](https://github.com/kirankotari/ossguard/releases):
41-
42-
```bash
43-
# macOS (Apple Silicon)
44-
curl -L https://github.com/kirankotari/ossguard/releases/latest/download/ossguard-macos-arm64 -o ossguard
45-
chmod +x ossguard && sudo mv ossguard /usr/local/bin/
46-
47-
# Linux (x86_64)
48-
curl -L https://github.com/kirankotari/ossguard/releases/latest/download/ossguard-linux-amd64 -o ossguard
49-
chmod +x ossguard && sudo mv ossguard /usr/local/bin/
50-
```
51-
52-
### Homebrew
53-
54-
```bash
55-
brew install kirankotari/tap/ossguard
56-
```
57-
58-
### Docker
59-
60-
```bash
61-
# Scan current directory
62-
docker run --rm -v "$(pwd):/project" ghcr.io/kirankotari/ossguard scan
63-
64-
# Bootstrap OpenSSF configs
65-
docker run --rm -v "$(pwd):/project" ghcr.io/kirankotari/ossguard init
66-
67-
# Any command works
68-
docker run --rm -v "$(pwd):/project" ghcr.io/kirankotari/ossguard audit
69-
```
70-
7121
## Quick Start
7222

7323
```bash
74-
# Bootstrap your project with all OpenSSF best practices
75-
cd your-project
76-
ossguard init
77-
78-
# Scan your project to see what's missing
79-
ossguard scan
80-
81-
# Run a full security audit
82-
ossguard audit
83-
84-
# Check OSPS Baseline compliance
85-
ossguard baseline
24+
ossguard scan . # Quick security posture check
25+
ossguard audit . # Full security audit
26+
ossguard init . # Bootstrap all OpenSSF configs
27+
ossguard baseline . # OSPS Baseline compliance
8628
```
8729

88-
## Commands
89-
90-
### Core
91-
92-
| Command | Description |
93-
|---------|-------------|
94-
| `ossguard init` | Bootstrap OpenSSF security configs (SECURITY.md, Scorecard, Dependabot, CodeQL, SBOM, Sigstore, branch protection) |
95-
| `ossguard scan` | Read-only security posture scan |
96-
| `ossguard version` | Show version |
97-
98-
### Dependency Analysis
99-
100-
| Command | Description |
101-
|---------|-------------|
102-
| `ossguard deps` | Dependency health analysis — vulns (OSV), outdated packages, risk scores (deps.dev) |
103-
| `ossguard drift` | SBOM diff between releases — detect added, removed, and changed dependencies |
104-
| `ossguard watch` | Continuous vulnerability monitoring from an SBOM (post-deployment watch) |
105-
| `ossguard tpn` | Generate third-party notices from project dependencies |
106-
107-
### Security Analysis
108-
109-
| Command | Description |
110-
|---------|-------------|
111-
| `ossguard audit` | Comprehensive security audit (scan + deps + reachability combined) |
112-
| `ossguard reach` | Filter vulnerabilities by runtime reachability (static import analysis) |
113-
| `ossguard secrets` | Scan for leaked credentials and secrets (24 detection rules) |
114-
115-
### Compliance & Frameworks
116-
117-
| Command | Description |
118-
|---------|-------------|
119-
| `ossguard baseline` | Check against OSPS Security Baseline (34 controls, Levels 1-3) |
120-
| `ossguard badge` | Assess readiness for the OpenSSF Best Practices Badge |
121-
| `ossguard slsa` | Assess SLSA Build Level (Levels 1-4, 12 requirements) |
122-
| `ossguard maturity` | S2C2F supply chain maturity assessment (22 practices, Levels 1-4) |
123-
| `ossguard license` | Dependency license compliance and conflict detection |
124-
| `ossguard policy` | Org-wide security policy enforcement (JSON config) |
125-
126-
### Supply Chain
127-
128-
| Command | Description |
129-
|---------|-------------|
130-
| `ossguard supply-chain` | Malicious package detection + typosquatting analysis |
131-
| `ossguard pin` | Pin GitHub Actions to commit SHAs (resolve tags to full SHAs) |
132-
| `ossguard update` | Security-prioritized dependency update suggestions |
133-
134-
### Generation
135-
136-
| Command | Description |
137-
|---------|-------------|
138-
| `ossguard insights` | Generate or validate SECURITY-INSIGHTS.yml |
139-
| `ossguard sbom-gen` | Generate local SBOM (SPDX 2.3 or CycloneDX 1.5) |
140-
| `ossguard ci` | Generate unified CI security pipeline (GitHub Actions) |
141-
| `ossguard report` | Export HTML or JSON compliance report |
142-
| `ossguard fuzz` | Fuzzing readiness check + starter harness generation (7 languages) |
143-
144-
### Container & Comparison
145-
146-
| Command | Description |
147-
|---------|-------------|
148-
| `ossguard container` | Dockerfile security linting (12 rules) |
149-
| `ossguard compare` | Side-by-side security posture comparison of two projects |
150-
| `ossguard fix` | Auto-remediate common security issues |
151-
152-
## Auto-Detection
153-
154-
OSSGuard automatically detects:
155-
156-
- **Languages**: Python, JavaScript/TypeScript, Go, Rust, Java, C/C++, Ruby, PHP, C#
157-
- **Package Managers**: npm, yarn, pnpm, pip, poetry, cargo, go modules, maven, gradle
158-
- **Frameworks**: React, Vue, Angular, Next.js, Django, Flask, FastAPI, Express
159-
- **Existing Security Setup**: Won't overwrite existing configurations
30+
## Features
16031

161-
## What `ossguard init` Generates
32+
This is the **reference implementation** with the richest UI (Rich tables, colored panels, interactive prompts).
16233

163-
| File | Purpose | OpenSSF Reference |
164-
|------|---------|-------------------|
165-
| `SECURITY.md` | Vulnerability disclosure policy | [CVD Guide](https://github.com/ossf/oss-vulnerability-guide) |
166-
| `.github/workflows/scorecard.yml` | Automated security scoring | [Scorecard](https://scorecard.dev/) |
167-
| `.github/dependabot.yml` | Dependency update automation | [Best Practices](https://best.openssf.org/) |
168-
| `.github/workflows/codeql.yml` | Code scanning for vulnerabilities | [Security Tooling WG](https://github.com/ossf/wg-security-tooling) |
169-
| `.github/workflows/sbom.yml` | Software Bill of Materials generation | [SBOM Everywhere](https://github.com/ossf/sbom-everywhere) |
170-
| `.github/workflows/sigstore.yml` | Cryptographic signing of releases | [Sigstore](https://sigstore.dev/) |
171-
| `.github/BRANCH_PROTECTION.md` | Branch protection setup guide | [SCM Best Practices](https://best.openssf.org/SCM-BestPractices/) |
34+
- **27 commands** covering the full OpenSSF security lifecycle
35+
- **Rich terminal UI** with tables, panels, and progress indicators
36+
- **Auto-detection** of languages, package managers, and frameworks
37+
- **Python 3.9+** with dependencies: typer, rich, pyyaml, jinja2, questionary, httpx
17238

173-
## How It Relates to OpenSSF
39+
For the complete command reference and real-world output examples, see the main [ossguard](https://github.com/kirankotari/ossguard) README.
17440

175-
OSSGuard is **not** a replacement for any OpenSSF project. It's a **unifier** — it makes it trivially easy to adopt the best practices and tools that OpenSSF working groups have built:
41+
## Other Implementations
17642

177-
- **Best Practices WG** — SECURITY.md template, Best Practices Badge assessment
178-
- **Security Tooling WG** — CodeQL setup, SBOM generation, secret scanning
179-
- **Supply Chain Integrity WG** — Sigstore signing, SLSA assessment, S2C2F maturity
180-
- **Vulnerability Disclosures WG** — CVD-compliant SECURITY.md
181-
- **Securing Software Repos WG** — Dependabot, branch protection, GitHub Actions pinning
182-
- **OSPS Baseline** — Automated compliance checking across maturity levels
43+
| Implementation | Install | Best for |
44+
|---------------|---------|----------|
45+
| **[ossguard-go](https://github.com/kirankotari/ossguard-go)** | `brew install kirankotari/tap/ossguard` | CI pipelines, single binary |
46+
| **[ossguard-npm](https://github.com/kirankotari/ossguard-npm)** | `npx ossguard` | Node.js projects |
18347

18448
## Development
18549

18650
```bash
18751
# Clone and install
188-
git clone https://github.com/kirankotari/ossguard.git
189-
cd ossguard
52+
git clone https://github.com/kirankotari/ossguard-python.git
53+
cd ossguard-python
19054
pip install -e ".[dev]"
19155

192-
# Run tests
56+
# Run tests (147 tests)
19357
pytest
19458

19559
# Lint

0 commit comments

Comments
 (0)