cybora 0.1.0__py3-none-any.whl

cybora/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.0"
+__all__ = ["__version__"]

cybora/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

cybora/cli.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from . import __version__
+from .modules import dependencies, network, system
+from .modules import repo as repo_module
+from .modules import web as web_module
+from .reporting import print_result, write_json
+from .runner import build_result
+
+app = typer.Typer(
+    name="cybora",
+    help="Free modular defensive cybersecurity assessment platform.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.callback()
+def main(
+    version: bool | None = typer.Option(
+        None, "--version", callback=lambda value: _version_callback(value), is_eager=True
+    ),
+):
+    """Cybora CLI entry point."""
+    return None
+
+
+def _version_callback(value: bool):
+    if value:
+        typer.echo(f"cybora {__version__}")
+        raise typer.Exit()
+
+
+@app.command()
+def demo():
+    """Run a safe local demo using an in-memory sample."""
+    sample = [
+        {
+            "module": "demo",
+            "title": "Sample medium-risk finding",
+            "severity": "medium",
+            "description": "This is a demonstration finding.",
+            "target": "demo://local",
+            "remediation": "Replace the demo with a real authorized assessment.",
+        }
+    ]
+    console.print_json(json.dumps({"tool": "cybora", "version": __version__, "findings": sample}))
+
+
+@app.command()
+def web(target: str):
+    """Run a non-destructive website baseline assessment."""
+    result = build_result(target, web_module.scan(target))
+    print_result(result)
+
+
+@app.command()
+def repo(target: str = typer.Argument(".", help="Repository directory.")):
+    """Scan a local repository for common accidental secrets and risky patterns."""
+    result = build_result(target, repo_module.scan(target))
+    print_result(result)
+
+
+@app.command("deps")
+def deps_command(target: str = typer.Argument(..., help="Dependency file.")):
+    """Assess dependency pinning and source hygiene."""
+    result = build_result(target, dependencies.scan(target))
+    print_result(result)
+
+
+@app.command("system")
+def system_assess():
+    """Assess the local system without making privileged changes."""
+    result = build_result("local-system", system.scan())
+    print_result(result)
+
+
+@app.command("network")
+def network_assess():
+    """Check common service ports on loopback only."""
+    result = build_result("127.0.0.1", network.scan())
+    print_result(result)
+
+
+@app.command()
+def assess(
+    web_target: str | None = typer.Option(None, "--web", help="Authorized HTTP(S) target."),
+    repo_target: str | None = typer.Option(None, "--repo", help="Local repository."),
+    deps_target: str | None = typer.Option(None, "--deps", help="Dependency file."),
+    system_check: bool = typer.Option(False, "--system", help="Include local system assessment."),
+    network_check: bool = typer.Option(
+        False, "--network", help="Include loopback network assessment."
+    ),
+    output: str | None = typer.Option(None, "--output", help="Write JSON report to this path."),
+):
+    """Run multiple defensive assessments and combine findings into one report."""
+    findings = []
+    targets = []
+
+    if web_target:
+        findings.extend(web_module.scan(web_target))
+        targets.append(f"web:{web_target}")
+    if repo_target:
+        findings.extend(repo_module.scan(repo_target))
+        targets.append(f"repo:{repo_target}")
+    if deps_target:
+        findings.extend(dependencies.scan(deps_target))
+        targets.append(f"deps:{deps_target}")
+    if system_check:
+        findings.extend(system.scan())
+        targets.append("system:local")
+    if network_check:
+        findings.extend(network.scan())
+        targets.append("network:loopback")
+
+    if not targets:
+        raise typer.BadParameter("Choose at least one assessment option.")
+
+    result = build_result(" | ".join(targets), findings)
+    print_result(result)
+
+    if output:
+        write_json(result, output)
+        console.print(f"\n[green]JSON report written to {Path(output).resolve()}[/green]")
+
+
+if __name__ == "__main__":
+    app()

cybora/models.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Severity(StrEnum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+class Finding(BaseModel):
+    module: str
+    title: str
+    severity: Severity
+    description: str
+    target: str
+    evidence: str | None = None
+    remediation: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AssessmentResult(BaseModel):
+    tool: str = "cybora"
+    version: str
+    target: str
+    findings: list[Finding] = Field(default_factory=list)
+    risk_score: int = 0

cybora/modules/dependencies.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from ..models import Finding, Severity
+
+PINNED = re.compile(r"^[A-Za-z0-9_.-]+\s*(==|===|~=)\s*[^#\s]+$")
+
+
+def scan(path: str) -> list[Finding]:
+    file = Path(path).resolve()
+    if not file.exists():
+        return [
+            Finding(
+                module="deps",
+                title="Dependency file does not exist",
+                severity=Severity.HIGH,
+                description="The supplied dependency file was not found.",
+                target=str(file),
+                remediation="Provide an existing requirements or dependency file.",
+            )
+        ]
+
+    findings = []
+    for line_no, raw in enumerate(
+        file.read_text(encoding="utf-8", errors="ignore").splitlines(), 1
+    ):
+        line = raw.strip()
+        if not line or line.startswith("#") or line.startswith("-"):
+            continue
+        if line.startswith(("git+", "http://", "https://")):
+            findings.append(
+                Finding(
+                    module="deps",
+                    title="Direct URL dependency",
+                    severity=Severity.MEDIUM,
+                    description="A dependency is sourced directly from a URL instead of a normal package index.",
+                    target=f"{file.name}:{line_no}",
+                    evidence=line[:160],
+                    remediation="Prefer a trusted package release or a reviewed immutable source reference.",
+                )
+            )
+        elif not PINNED.match(line):
+            package = re.split(r"[<>=!~\s]", line, maxsplit=1)[0]
+            findings.append(
+                Finding(
+                    module="deps",
+                    title="Unpinned dependency",
+                    severity=Severity.LOW,
+                    description="The dependency does not use an exact or compatible version constraint.",
+                    target=f"{file.name}:{line_no}",
+                    evidence=package,
+                    remediation="Pin or constrain production dependencies and maintain a reviewed update process.",
+                )
+            )
+    return findings

cybora/modules/network.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import socket
+
+from ..models import Finding, Severity
+
+COMMON_LOCAL_PORTS = {
+    22: "SSH",
+    80: "HTTP",
+    443: "HTTPS",
+    3000: "Node development server",
+    5000: "Development server",
+    8000: "Python development server",
+    8080: "HTTP development/proxy",
+    8443: "HTTPS development server",
+}
+
+
+def scan(host: str = "127.0.0.1") -> list[Finding]:
+    findings = []
+    for port, label in COMMON_LOCAL_PORTS.items():
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(0.15)
+        try:
+            is_open = sock.connect_ex((host, port)) == 0
+        except OSError:
+            is_open = False
+        finally:
+            sock.close()
+
+        if is_open:
+            severity = Severity.LOW if port in {3000, 5000, 8000, 8080, 8443} else Severity.INFO
+            findings.append(
+                Finding(
+                    module="network",
+                    title=f"Local service reachable: {label}",
+                    severity=severity,
+                    description="A common service port accepted a TCP connection on the loopback interface.",
+                    target=f"{host}:{port}",
+                    remediation="Confirm the service is intentional and appropriately protected. Do not expose development services to untrusted networks.",
+                )
+            )
+    return findings

cybora/modules/repo.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from ..models import Finding, Severity
+
+SECRET_PATTERNS = [
+    ("AWS access key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    (
+        "Generic API key assignment",
+        re.compile(r"(?i)\b(api[_-]?key|secret[_-]?key)\s*[:=]\s*['\"][^'\"]{12,}['\"]"),
+    ),
+    ("Private key marker", re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----")),
+    (
+        "Generic password assignment",
+        re.compile(r"(?i)\b(password|passwd|pwd)\s*[:=]\s*['\"][^'\"]{8,}['\"]"),
+    ),
+]
+
+RISKY_NAMES = {".env", "id_rsa", "id_ed25519", "credentials.json", "secrets.json"}
+
+
+def scan(path: str) -> list[Finding]:
+    root = Path(path).resolve()
+    findings: list[Finding] = []
+
+    if not root.exists():
+        return [
+            Finding(
+                module="repo",
+                title="Repository path does not exist",
+                severity=Severity.HIGH,
+                description="The requested repository path could not be found.",
+                target=str(root),
+                remediation="Check the path and run the assessment again.",
+            )
+        ]
+
+    for file in _files(root):
+        rel = str(file.relative_to(root))
+        if file.name in RISKY_NAMES:
+            findings.append(
+                Finding(
+                    module="repo",
+                    title="Sensitive-looking file present",
+                    severity=Severity.MEDIUM,
+                    description="A file commonly used for credentials or secrets exists in the repository.",
+                    target=rel,
+                    remediation="Verify it contains no real secrets and keep credential files out of version control.",
+                )
+            )
+
+        if file.stat().st_size > 25 * 1024 * 1024:
+            findings.append(
+                Finding(
+                    module="repo",
+                    title="Very large file",
+                    severity=Severity.LOW,
+                    description="Large files can increase repository exposure and supply-chain review burden.",
+                    target=rel,
+                    evidence=f"{file.stat().st_size} bytes",
+                    remediation="Use an appropriate artifact store or Git LFS when justified.",
+                )
+            )
+
+        if file.suffix.lower() not in {
+            ".py",
+            ".js",
+            ".ts",
+            ".json",
+            ".yaml",
+            ".yml",
+            ".toml",
+            ".ini",
+            ".env",
+            ".txt",
+            ".md",
+        }:
+            continue
+
+        try:
+            text = file.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+
+        for label, pattern in SECRET_PATTERNS:
+            if pattern.search(text):
+                findings.append(
+                    Finding(
+                        module="repo",
+                        title=f"Possible {label}",
+                        severity=Severity.HIGH,
+                        description="A heuristic pattern resembling a credential or private key was found.",
+                        target=rel,
+                        remediation="Inspect the exact line, remove real secrets, rotate exposed credentials, and use a secret manager.",
+                    )
+                )
+
+        if re.search(r"(?m)^\s*eval\s*\(", text):
+            findings.append(
+                Finding(
+                    module="repo",
+                    title="Dynamic eval usage",
+                    severity=Severity.MEDIUM,
+                    description="Dynamic evaluation can increase code-injection risk depending on data flow.",
+                    target=rel,
+                    remediation="Avoid eval where possible and validate untrusted input before any dynamic execution.",
+                )
+            )
+
+    return _dedupe(findings)
+
+
+def _files(root: Path):
+    ignored = {".git", ".venv", "__pycache__", "node_modules", ".pytest_cache"}
+    for p in root.rglob("*"):
+        if p.is_file() and not any(part in ignored for part in p.parts):
+            yield p
+
+
+def _dedupe(findings: list[Finding]) -> list[Finding]:
+    seen = set()
+    result = []
+    for f in findings:
+        key = (f.module, f.title, f.target)
+        if key not in seen:
+            seen.add(key)
+            result.append(f)
+    return result

cybora/modules/system.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from pathlib import Path
+
+from ..models import Finding, Severity
+
+
+def scan() -> list[Finding]:
+    findings = [
+        Finding(
+            module="system",
+            title="Runtime inventory",
+            severity=Severity.INFO,
+            description="Basic local runtime information was collected for the report.",
+            target=platform.node() or "localhost",
+            evidence=f"OS={platform.platform()} | Python={sys.version.split()[0]}",
+            remediation="Keep the operating system and runtime on supported security-maintained versions.",
+        )
+    ]
+
+    if os.name == "nt":
+        findings.append(
+            Finding(
+                module="system",
+                title="Windows local security review reminder",
+                severity=Severity.INFO,
+                description="The foundation release does not attempt privileged Windows security configuration changes.",
+                target=platform.node() or "localhost",
+                remediation="Review Windows Update, Defender, firewall, disk encryption, account protection, and least privilege using your organization's baseline.",
+            )
+        )
+    else:
+        findings.append(
+            Finding(
+                module="system",
+                title="Local permissions review reminder",
+                severity=Severity.INFO,
+                description="The foundation release avoids privileged host changes.",
+                target=str(Path.home()),
+                remediation="Review account privileges, updates, firewall configuration, SSH access, and sensitive file permissions.",
+            )
+        )
+    return findings

cybora/modules/web.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+import httpx
+
+from ..models import Finding, Severity
+
+SECURITY_HEADERS = {
+    "strict-transport-security": (
+        Severity.MEDIUM,
+        "Missing HSTS",
+        "Consider Strict-Transport-Security for HTTPS deployments after validating deployment behavior.",
+    ),
+    "content-security-policy": (
+        Severity.MEDIUM,
+        "Missing Content-Security-Policy",
+        "Deploy a carefully tested Content-Security-Policy appropriate to the application.",
+    ),
+    "x-content-type-options": (
+        Severity.LOW,
+        "Missing X-Content-Type-Options",
+        "Set X-Content-Type-Options: nosniff where appropriate.",
+    ),
+    "referrer-policy": (
+        Severity.LOW,
+        "Missing Referrer-Policy",
+        "Set a deliberate Referrer-Policy suitable for your application.",
+    ),
+    "permissions-policy": (
+        Severity.INFO,
+        "Missing Permissions-Policy",
+        "Review whether browser feature permissions should be restricted.",
+    ),
+}
+
+
+def scan(url: str) -> list[Finding]:
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        return [
+            Finding(
+                module="web",
+                title="Invalid web target",
+                severity=Severity.HIGH,
+                description="The supplied value is not a valid HTTP(S) URL.",
+                target=url,
+                remediation="Use a URL such as https://example.com.",
+            )
+        ]
+
+    findings = []
+    try:
+        with httpx.Client(
+            follow_redirects=True,
+            timeout=8.0,
+            verify=True,
+            headers={"User-Agent": "Cybora/0.1 defensive-assessment"},
+        ) as client:
+            response = client.get(url)
+    except httpx.HTTPError as exc:
+        return [
+            Finding(
+                module="web",
+                title="Web target could not be reached",
+                severity=Severity.HIGH,
+                description="The HTTP client could not complete a connection.",
+                target=url,
+                evidence=str(exc)[:300],
+                remediation="Verify the URL, connectivity, DNS, and authorization to assess the target.",
+            )
+        ]
+
+    final_url = str(response.url)
+    if parsed.scheme == "http" and urlparse(final_url).scheme != "https":
+        findings.append(
+            Finding(
+                module="web",
+                title="HTTP target did not end on HTTPS",
+                severity=Severity.HIGH,
+                description="The requested HTTP URL did not redirect to HTTPS.",
+                target=url,
+                remediation="Prefer HTTPS and configure a deliberate HTTP-to-HTTPS redirect.",
+            )
+        )
+
+    headers = {k.lower(): v for k, v in response.headers.items()}
+    for header, (severity, title, remediation) in SECURITY_HEADERS.items():
+        if header not in headers:
+            findings.append(
+                Finding(
+                    module="web",
+                    title=title,
+                    severity=severity,
+                    description=f"The response did not include the {header} header.",
+                    target=final_url,
+                    remediation=remediation,
+                )
+            )
+
+    server = headers.get("server")
+    if server:
+        findings.append(
+            Finding(
+                module="web",
+                title="Server header disclosed",
+                severity=Severity.LOW,
+                description="The HTTP response discloses a server identification header.",
+                target=final_url,
+                evidence=server[:120],
+                remediation="Consider whether detailed server identification is necessary.",
+            )
+        )
+
+    set_cookie = headers.get("set-cookie", "")
+    if set_cookie:
+        lower = set_cookie.lower()
+        if "secure" not in lower and urlparse(final_url).scheme == "https":
+            findings.append(
+                Finding(
+                    module="web",
+                    title="Cookie without Secure attribute observed",
+                    severity=Severity.MEDIUM,
+                    description="A Set-Cookie response did not visibly include the Secure attribute.",
+                    target=final_url,
+                    remediation="Use Secure on cookies carrying sensitive session state over HTTPS.",
+                )
+            )
+        if "httponly" not in lower:
+            findings.append(
+                Finding(
+                    module="web",
+                    title="Cookie without HttpOnly attribute observed",
+                    severity=Severity.LOW,
+                    description="A Set-Cookie response did not visibly include HttpOnly.",
+                    target=final_url,
+                    remediation="Use HttpOnly for cookies that do not need JavaScript access.",
+                )
+            )
+
+    findings.append(
+        Finding(
+            module="web",
+            title="HTTP response observed",
+            severity=Severity.INFO,
+            description="A non-destructive HTTP request completed.",
+            target=final_url,
+            evidence=f"status={response.status_code}; content-type={headers.get('content-type', 'unknown')}",
+            remediation="Use the findings above as a baseline; application security requires deeper authorized testing.",
+        )
+    )
+
+    return findings

cybora/reporting.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+from .models import AssessmentResult
+
+console = Console()
+
+
+def print_result(result: AssessmentResult) -> None:
+    console.print("\n[bold]CYBORA SECURITY ASSESSMENT[/bold]\n")
+    console.print(f"Target: {result.target}")
+    console.print(f"Findings: {len(result.findings)}")
+    console.print(f"Risk score: {result.risk_score}/100\n")
+
+    if not result.findings:
+        console.print("[green]No findings in the selected checks.[/green]")
+        return
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Severity")
+    table.add_column("Module")
+    table.add_column("Finding")
+    table.add_column("Target")
+
+    for finding in sorted(result.findings, key=lambda x: _rank(x.severity.value)):
+        table.add_row(
+            finding.severity.value.upper(),
+            finding.module,
+            finding.title,
+            finding.target,
+        )
+
+    console.print(table)
+    console.print("\n[bold]Priority guidance[/bold]")
+    for i, finding in enumerate(
+        sorted(result.findings, key=lambda x: _rank(x.severity.value))[:5], start=1
+    ):
+        console.print(f"{i}. {finding.title}: {finding.remediation or 'Review manually.'}")
+
+
+def write_json(result: AssessmentResult, path: str | Path) -> None:
+    Path(path).write_text(
+        json.dumps(result.model_dump(mode="json"), indent=2),
+        encoding="utf-8",
+    )
+
+
+def _rank(severity: str) -> int:
+    return {
+        "critical": 0,
+        "high": 1,
+        "medium": 2,
+        "low": 3,
+        "info": 4,
+    }.get(severity, 5)