devguard 0.2.0__py3-none-any.whl

devguard/sarif.py

@@ -0,0 +1,295 @@
+"""Convert devguard sweep reports to SARIF 2.1.0 format."""
+
+from __future__ import annotations
+
+from typing import Any
+
+SARIF_SCHEMA = (
+    "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/"
+    "sarif-2.1/schema/sarif-schema-2.1.0.json"
+)
+
+# Map severity strings used across sweeps to SARIF levels.
+_SEVERITY_TO_LEVEL: dict[str, str] = {
+    "error": "error",
+    "critical": "error",
+    "high": "error",
+    "warning": "warning",
+    "medium": "warning",
+    "info": "note",
+    "note": "note",
+    "low": "note",
+}
+
+
+def _sarif_level(severity: str) -> str:
+    return _SEVERITY_TO_LEVEL.get(severity.lower(), "warning")
+
+
+# ---------------------------------------------------------------------------
+# Per-sweep extractors
+# ---------------------------------------------------------------------------
+# Each returns a list of (rule_id, level, message, uri | None) tuples.
+
+
+def _extract_ai_editor_config(report: dict) -> list[tuple[str, str, str, str | None]]:
+    results: list[tuple[str, str, str, str | None]] = []
+    for repo in report.get("repos", []):
+        repo_path = repo.get("repo_path") or repo.get("repo_name")
+        for f in repo.get("findings", []):
+            results.append(
+                (
+                    f.get("check", "unknown"),
+                    _sarif_level(f.get("severity", "warning")),
+                    f.get("message", ""),
+                    repo_path,
+                )
+            )
+    return results
+
+
+def _extract_cargo_publish(report: dict) -> list[tuple[str, str, str, str | None]]:
+    # Same shape as ai_editor_config: repos[].findings[].{check, severity, message}
+    return _extract_ai_editor_config(report)
+
+
+def _extract_gitignore_audit(report: dict) -> list[tuple[str, str, str, str | None]]:
+    results: list[tuple[str, str, str, str | None]] = []
+    for repo in report.get("repos", []):
+        repo_path = repo.get("repo_path")
+        is_public = repo.get("is_public", False)
+        level = "error" if is_public else "warning"
+        if not repo.get("has_gitignore"):
+            results.append(
+                (
+                    "missing_gitignore",
+                    level,
+                    "Repository has no .gitignore file",
+                    repo_path,
+                )
+            )
+        for pattern in repo.get("missing_patterns", []):
+            results.append(
+                (
+                    "missing_gitignore_pattern",
+                    level,
+                    f"Missing gitignore pattern: {pattern}",
+                    repo_path,
+                )
+            )
+        for warn in repo.get("case_warnings", []):
+            results.append(
+                (
+                    "gitignore_case_warning",
+                    "note",
+                    warn if isinstance(warn, str) else str(warn),
+                    repo_path,
+                )
+            )
+    return results
+
+
+def _extract_dependency_audit(report: dict) -> list[tuple[str, str, str, str | None]]:
+    results: list[tuple[str, str, str, str | None]] = []
+    for repo in report.get("repos", []):
+        repo_path = repo.get("repo_path")
+        for v in repo.get("vulns", []):
+            sev = v.get("severity", "unknown")
+            pkg = v.get("package", "?")
+            title = v.get("title", "")
+            vid = v.get("id", "unknown")
+            msg = f"{vid}: {pkg} - {title}" if title else f"{vid}: {pkg}"
+            results.append(
+                (
+                    f"dependency_vuln_{sev}",
+                    _sarif_level(sev),
+                    msg,
+                    repo_path,
+                )
+            )
+    return results
+
+
+def _extract_ssh_key_audit(report: dict) -> list[tuple[str, str, str, str | None]]:
+    results: list[tuple[str, str, str, str | None]] = []
+    for key in report.get("keys", []):
+        key_file = key.get("file")
+        for issue in key.get("issues", []):
+            results.append(
+                (
+                    "ssh_key_issue",
+                    "warning",
+                    issue,
+                    key_file,
+                )
+            )
+    return results
+
+
+def _extract_public_github_secrets(report: dict) -> list[tuple[str, str, str, str | None]]:
+    results: list[tuple[str, str, str, str | None]] = []
+    for f in report.get("findings", []):
+        detector = f.get("type", "unknown")
+        repo = f.get("repo", "")
+        file_path = f.get("file")
+        verified = f.get("verified")
+        level = "error" if verified else "warning"
+        msg = f"Secret detected: {detector} in {repo}"
+        if file_path:
+            msg += f" ({file_path})"
+        uri = file_path if file_path else repo
+        results.append(
+            (
+                f"secret_{detector}",
+                level,
+                msg,
+                uri,
+            )
+        )
+    return results
+
+
+def _extract_local_dirty_worktree_secrets(report: dict) -> list[tuple[str, str, str, str | None]]:
+    # Same top-level findings[] shape as public_github_secrets
+    return _extract_public_github_secrets(report)
+
+
+def _extract_local_dev(report: dict) -> list[tuple[str, str, str, str | None]]:
+    results: list[tuple[str, str, str, str | None]] = []
+    for hit in report.get("hits", []):
+        reason = hit.get("reason", "flagged file")
+        file_path = hit.get("file_path")
+        repo_path = hit.get("repo_path")
+        uri = file_path or repo_path
+        results.append(
+            (
+                "local_dev_hit",
+                "warning",
+                reason,
+                uri,
+            )
+        )
+    return results
+
+
+def _extract_project_flaudit(report: dict) -> list[tuple[str, str, str, str | None]]:
+    results: list[tuple[str, str, str, str | None]] = []
+    for repo in report.get("repos", report.get("results", [])):
+        repo_path = repo.get("repo_path") or repo.get("repo_name", "")
+        for f in repo.get("findings", []):
+            # project_flaudit findings may have check/severity/message or
+            # category/severity/description
+            check = f.get("check") or f.get("category", "unknown")
+            sev = f.get("severity", "warning")
+            msg = f.get("message") or f.get("description", "")
+            results.append(
+                (
+                    check,
+                    _sarif_level(sev),
+                    msg,
+                    repo_path,
+                )
+            )
+    return results
+
+
+_EXTRACTORS: dict[str, Any] = {
+    "ai_editor_config_audit": _extract_ai_editor_config,
+    "cargo_publish_audit": _extract_cargo_publish,
+    "gitignore_audit": _extract_gitignore_audit,
+    "dependency_audit": _extract_dependency_audit,
+    "ssh_key_audit": _extract_ssh_key_audit,
+    "public_github_secrets": _extract_public_github_secrets,
+    "local_dirty_worktree_secrets": _extract_local_dirty_worktree_secrets,
+    "local_dev": _extract_local_dev,
+    "project_flaudit": _extract_project_flaudit,
+}
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def report_to_sarif(
+    report: dict,
+    sweep_name: str,
+    tool_version: str = "0.1.0",
+) -> dict:
+    """Convert a devguard sweep report to SARIF 2.1.0 format."""
+    extractor = _EXTRACTORS.get(sweep_name)
+    if extractor is None:
+        # Fallback: try the ai_editor_config shape (repos[].findings[])
+        extractor = _extract_ai_editor_config
+
+    raw_results = extractor(report)
+
+    # Collect unique rule IDs
+    rule_ids: dict[str, int] = {}
+    rules: list[dict] = []
+    for rule_id, _level, _msg, _uri in raw_results:
+        if rule_id not in rule_ids:
+            rule_ids[rule_id] = len(rules)
+            rules.append(
+                {
+                    "id": rule_id,
+                    "shortDescription": {"text": rule_id.replace("_", " ")},
+                }
+            )
+
+    sarif_results: list[dict] = []
+    for rule_id, level, message, uri in raw_results:
+        result: dict[str, Any] = {
+            "ruleId": rule_id,
+            "ruleIndex": rule_ids[rule_id],
+            "level": level,
+            "message": {"text": message},
+        }
+        if uri:
+            result["locations"] = [
+                {
+                    "physicalLocation": {
+                        "artifactLocation": {"uri": uri},
+                    },
+                }
+            ]
+        sarif_results.append(result)
+
+    return {
+        "$schema": SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "devguard",
+                        "version": tool_version,
+                        "informationUri": "https://github.com/arclabs561/devguard",
+                        "rules": rules,
+                    },
+                },
+                "results": sarif_results,
+            }
+        ],
+    }
+
+
+def reports_to_sarif(
+    sweep_reports: list[tuple[str, dict]],
+    tool_version: str = "0.1.0",
+) -> dict:
+    """Convert multiple sweep reports into a single SARIF document.
+
+    Each entry in sweep_reports is (sweep_name, report_dict).
+    Each sweep becomes a separate run in the SARIF output.
+    """
+    runs: list[dict] = []
+    for sweep_name, report in sweep_reports:
+        single = report_to_sarif(report, sweep_name, tool_version=tool_version)
+        runs.extend(single["runs"])
+
+    return {
+        "$schema": SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": runs,
+    }

devguard/scripts/ANALYSIS_SUMMARY.md

@@ -0,0 +1,141 @@
+# NPM Package Red Team Analysis - Complete Summary
+
+## Analysis Results
+
+**Date:** 2025-11-17  
+**Packages Analyzed:** 5
+
+### Security Status: ✅ CLEAN
+
+All packages passed comprehensive security analysis with no critical issues found.
+
+## Detailed Findings
+
+### Secrets & Credentials
+- **Secrets Found:** 0
+- **Base64/Hex Encoded Secrets:** 0
+- **Secrets in Test Files:** 0
+- **Secrets in Comments:** 0
+
+### Code Security
+- **Obfuscated Code Patterns:** 19 (all low severity - legitimate uses)
+- **Suspicious Scripts:** 0
+- **Placeholder Values:** 0
+
+### File Security
+- **Sensitive Files:** 0
+- **Git History Published:** 0
+- **Lock Files Published:** 0
+- **CI/CD Configs:** 0
+- **Unusual File Permissions:** 0
+
+### Package Configuration
+- **Missing .npmignore:** 5 packages (recommendation to add)
+- **Files Field Issues:** Minor (package.json not in files list)
+- **Suspicious Package Names:** 0
+
+### Dependencies
+- **Vulnerabilities:** 0
+- **Critical/High Severity:** 0
+- **Install Scripts:** 1 (review recommended)
+
+## Recommendations
+
+### High Priority
+1. **Add .npmignore files** to all 5 packages
+   - Command: `uv run python devguard/scripts/generate_npmignore.py`
+   - Improves security by explicitly excluding sensitive files
+
+### Medium Priority
+1. **Review obfuscated code patterns** (19 instances)
+   - All flagged as low severity
+   - Verify Function(), atob() usage is legitimate
+   - Most likely false positives for data encoding
+
+2. **Review install scripts** (1 instance)
+   - Check postinstall/preinstall scripts for security risks
+   - Ensure no malicious network requests
+
+## Analysis Capabilities
+
+### Secret Detection
+- 20+ secret pattern types
+- Base64/hex decoding and validation
+- Context-aware filtering (test values, examples)
+- OpenAI, Anthropic, AWS, GitHub, Stripe keys
+- Database URLs, OAuth secrets, JWT secrets
+
+### Code Analysis
+- Context-aware obfuscation detection
+- Legitimate use pattern filtering
+- Suspicious variable name detection
+- Multi-factor severity assessment
+
+### File Analysis
+- Sensitive file name detection
+- Git history detection
+- Lock file detection
+- CI/CD config detection
+- Source map detection
+- Large file detection
+- File permission analysis
+
+### Package Analysis
+- package.json deep analysis
+- Script security review
+- Dependency risk assessment
+- Package name typosquatting detection
+- Files field validation
+
+### Dependency Security
+- npm audit integration
+- Vulnerability severity assessment
+- CVE tracking
+- Critical/High prioritization
+
+## Tools Created
+
+1. **redteam_npm_packages.py** (47KB)
+   - Comprehensive security analysis
+   - Real-time vulnerability checking
+   - Detailed reporting
+
+2. **generate_npmignore.py** (4.8KB)
+   - Automated .npmignore generation
+   - Best practices based
+   - Backup creation
+
+3. **generate_security_report.py** (10.6KB)
+   - JSON and Markdown reports
+   - Prioritized recommendations
+   - Comprehensive statistics
+
+4. **auto_fix_recommendations.py** (4.8KB)
+   - Automated fix suggestions
+   - Command generation
+   - Priority-based actions
+
+5. **prepublish_check.sh** (785B)
+   - Pre-publish hook integration
+   - Automated security checks
+   - Fail-safe publishing
+
+## Next Steps
+
+1. Generate .npmignore files for all packages
+2. Review the 1 install script found
+3. Verify obfuscated code patterns are legitimate
+4. Integrate pre-publish hooks into package.json
+5. Set up regular security audits
+
+## Continuous Improvement
+
+The analysis system is designed to:
+- Reduce false positives through context awareness
+- Add new secret patterns as threats evolve
+- Improve detection accuracy over time
+- Provide actionable, prioritized recommendations
+
+All packages are secure and ready for continued use! 🎉
+
+

devguard/scripts/README.md

@@ -0,0 +1,221 @@
+# devguard NPM Security Scripts
+
+Comprehensive security analysis and remediation tools for npm packages.
+
+## Scripts
+
+### `redteam_npm_packages.py`
+
+Deep red team security analysis of published npm packages.
+
+**Features:**
+- **Secret Detection:**
+  - API keys (OpenAI, Anthropic, AWS, GitHub, Stripe, etc.)
+  - Tokens and passwords
+  - Database URLs
+  - OAuth secrets
+  - JWT secrets
+  - Base64/hex encoded secrets (with decoding)
+  
+- **Code Analysis:**
+  - Context-aware obfuscated code detection (eval, Function, atob, etc.)
+  - Suspicious script patterns
+  - Placeholder values
+  - Secrets in comments
+  
+- **File Analysis:**
+  - Sensitive file names
+  - Git history detection
+  - Lock files
+  - CI/CD configs
+  - Source maps
+  - Large files
+  - File permissions
+  
+- **Package Configuration:**
+  - Missing .npmignore
+  - Files field analysis
+  - Suspicious install scripts (postinstall/preinstall)
+  - Dependency risk assessment
+  - Package name typosquatting detection
+  
+- **Dependency Security:**
+  - npm audit integration
+  - Vulnerability severity assessment
+  - CVE tracking
+
+**Usage:**
+```bash
+uv run python devguard/scripts/redteam_npm_packages.py
+```
+
+**Output:**
+- Detailed per-package analysis with severity ratings
+- Summary statistics
+- Prioritized actionable recommendations
+
+### `generate_npmignore.py`
+
+Generate `.npmignore` files based on npm best practices.
+
+**Usage:**
+```bash
+# Generate for all packages in default location (~/Documents/dev)
+uv run python devguard/scripts/generate_npmignore.py
+
+# Generate for specific directory
+uv run python devguard/scripts/generate_npmignore.py /path/to/packages
+```
+
+**Features:**
+- Excludes test files
+- Excludes CI/CD configs
+- Excludes sensitive files
+- Excludes lock files
+- Creates backups of existing files
+- Customizable based on package structure
+
+### `generate_security_report.py`
+
+Generate comprehensive JSON and Markdown security reports.
+
+**Usage:**
+```bash
+uv run python devguard/scripts/generate_security_report.py
+```
+
+**Output:**
+- `npm_security_report.json` - Detailed JSON report with all findings
+- `npm_security_report.md` - Human-readable Markdown report
+- Summary statistics
+- Prioritized recommendations (HIGH/MEDIUM/LOW)
+
+### `auto_fix_recommendations.py`
+
+Generate automated fix commands based on security analysis.
+
+**Usage:**
+```bash
+uv run python devguard/scripts/auto_fix_recommendations.py
+```
+
+**Features:**
+- Analyzes security report
+- Generates fix commands
+- Optionally applies fixes automatically
+- Prioritizes by severity
+
+## Best Practices
+
+1. **Run analysis before publishing:**
+   ```bash
+   uv run python devguard/scripts/redteam_npm_packages.py
+   ```
+
+2. **Generate .npmignore files:**
+   ```bash
+   uv run python devguard/scripts/generate_npmignore.py
+   ```
+
+3. **Review install scripts** - Especially `postinstall` and `preinstall` scripts
+
+4. **Use `files` field** in package.json instead of `.npmignore` when possible (more secure allowlist)
+
+5. **Never publish:**
+   - `.env` files
+   - `.git` directory
+   - Lock files
+   - CI/CD configs with secrets
+   - Test files with real credentials
+
+6. **Regular audits:**
+   ```bash
+   npm audit
+   npm audit fix
+   ```
+
+## Integration
+
+Add to your `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "prepublishOnly": "python devguard/scripts/redteam_npm_packages.py",
+    "check:security": "python devguard/scripts/redteam_npm_packages.py",
+    "fix:security": "python devguard/scripts/auto_fix_recommendations.py"
+  }
+}
+```
+
+## Security Checks Performed
+
+### Secret Detection
+- API keys (OpenAI, Anthropic, AWS, GitHub, Stripe, etc.)
+- Tokens and passwords
+- Database URLs
+- OAuth secrets
+- JWT secrets
+- Base64/hex encoded secrets (with automatic decoding)
+
+### Code Analysis
+- Context-aware obfuscated code detection
+- Suspicious script patterns
+- Placeholder values
+- Secrets in comments
+- Install script security risks
+
+### File Analysis
+- Sensitive file names
+- Git history
+- Lock files
+- CI/CD configs
+- Source maps
+- Large files
+- File permissions
+
+### Package Configuration
+- Missing .npmignore
+- Files field issues
+- Suspicious install scripts
+- Dependency risks
+- Repository exposure
+- Package name typosquatting
+
+### Dependency Security
+- npm audit integration
+- Vulnerability severity assessment
+- CVE tracking
+- Critical/High severity prioritization
+
+## Continuous Improvement
+
+The analysis continuously improves with:
+- New secret patterns
+- Better false positive filtering
+- Additional security checks
+- Enhanced reporting
+- Context-aware detection
+
+Run regularly to catch issues before they're published!
+
+## Workflow
+
+1. **Before publishing:**
+   ```bash
+   uv run python devguard/scripts/redteam_npm_packages.py
+   ```
+
+2. **Fix issues:**
+   ```bash
+   uv run python devguard/scripts/auto_fix_recommendations.py
+   ```
+
+3. **Generate reports:**
+   ```bash
+   uv run python devguard/scripts/generate_security_report.py
+   ```
+
+4. **Review and commit fixes**
+
+5. **Publish with confidence!**