reconax 0.2.0__py3-none-any.whl

reconax/__init__.py

@@ -0,0 +1,98 @@
+"""ReconAx - lightweight, developer-friendly website analyzer."""
+
+from .core import ReconAx
+from .models import (
+    ReconReport,
+    HTTPResponse,
+    HeaderAnalysis,
+    CookieInfo,
+    CookieAnalysis,
+    HTMLAnalysis,
+    RobotsAnalysis,
+    DNSAnalysis,
+    TLSAnalysis,
+    Technology,
+    TechAnalysis,
+    SitemapAnalysis,
+    CORSAnalysis,
+    CSPAnalysis,
+    SRIAnalysis,
+    SecurityTxtAnalysis,
+    MetadataAnalysis,
+    ResourceInfo,
+    ResourceAnalysis,
+    EndpointInfo,
+    EndpointAnalysis,
+    AttackSurfaceAnalysis,
+    ScoreItem,
+    ScoreReport,
+)
+from .shortcuts import (
+    analyze,
+    headers,
+    cookies,
+    html,
+    robots,
+    dns,
+    tls,
+    tech,
+    sitemap,
+    cors,
+    csp,
+    sri,
+    security_txt,
+    metadata,
+    resources,
+    endpoints,
+    attack_surface,
+    score,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "ReconAx",
+    "ReconReport",
+    "HTTPResponse",
+    "HeaderAnalysis",
+    "CookieInfo",
+    "CookieAnalysis",
+    "HTMLAnalysis",
+    "RobotsAnalysis",
+    "DNSAnalysis",
+    "TLSAnalysis",
+    "Technology",
+    "TechAnalysis",
+    "SitemapAnalysis",
+    "CORSAnalysis",
+    "CSPAnalysis",
+    "SRIAnalysis",
+    "SecurityTxtAnalysis",
+    "MetadataAnalysis",
+    "ResourceInfo",
+    "ResourceAnalysis",
+    "EndpointInfo",
+    "EndpointAnalysis",
+    "AttackSurfaceAnalysis",
+    "ScoreItem",
+    "ScoreReport",
+    "analyze",
+    "headers",
+    "cookies",
+    "html",
+    "robots",
+    "dns",
+    "tls",
+    "tech",
+    "sitemap",
+    "cors",
+    "csp",
+    "sri",
+    "security_txt",
+    "metadata",
+    "resources",
+    "endpoints",
+    "attack_surface",
+    "score",
+    "__version__",
+]

reconax/cli.py

@@ -0,0 +1,213 @@
+"""Command-line interface for ReconAx."""
+
+from __future__ import annotations
+
+import sys
+
+from pathlib import Path
+from typing import Any, Callable
+
+# Ensure UTF-8 encoding on Windows to prevent charmap errors with Rich Unicode
+if sys.stdout.encoding != "UTF-8":
+    sys.stdout.reconfigure(encoding="utf-8")
+if sys.stderr.encoding != "UTF-8":
+    sys.stderr.reconfigure(encoding="utf-8")
+
+import typer
+
+from .core import ReconAx
+from .formatters.json_out import report_to_json, result_to_json
+from .formatters.rich_out import render_report, render_result
+
+app = typer.Typer(
+    name="reconax",
+    help="⚡ ReconAx - lightweight, developer-friendly website analyzer.",
+    no_args_is_help=True,
+    add_completion=True,
+)
+
+
+def _write_output(content: str, output_file: str | None) -> None:
+    if output_file:
+        Path(output_file).write_text(content, encoding="utf-8")
+        typer.echo(f"Report written to {output_file}")
+    else:
+        typer.echo(content)
+
+
+def _run_module(
+    url: str,
+    method: str,
+    *,
+    as_json: bool = False,
+    explain: bool = False,
+    output_file: str | None = None,
+    timeout: float = 10.0,
+) -> None:
+    recon = ReconAx(url, timeout=timeout)
+    try:
+        result = getattr(recon, method)()
+        if as_json:
+            _write_output(result_to_json(result), output_file)
+        elif output_file:
+            raise typer.BadParameter("Use --json with -o/--output.")
+        else:
+            render_result(result, explain=explain)
+    except ValueError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1)
+    except typer.Exit:
+        raise
+    except Exception as exc:
+        typer.echo(f"ReconAx error: {exc}", err=True)
+        raise typer.Exit(code=1)
+    finally:
+        recon.close()
+
+
+def _module_command(
+    url: str,
+    method: str,
+    explain: bool,
+    json_output: bool,
+    timeout: float,
+) -> None:
+    _run_module(
+        url,
+        method,
+        explain=explain,
+        as_json=json_output,
+        timeout=timeout,
+    )
+
+
+@app.command("analyze")
+def analyze_command(
+    url: str = typer.Argument(..., help="Target HTTP/HTTPS URL."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+    explain: bool = typer.Option(False, "--explain", help="Show explanations."),
+    no_dns: bool = typer.Option(False, "--no-dns", help="Skip DNS analysis."),
+    timeout: float = typer.Option(10.0, "--timeout", min=0.1),
+    output: str | None = typer.Option(None, "-o", "--output", help="Write JSON to a file."),
+) -> None:
+    recon = ReconAx(url, timeout=timeout)
+    try:
+        report = recon.analyze(include_dns=not no_dns)
+        if json_output:
+            _write_output(report_to_json(report), output)
+        elif output:
+            raise typer.BadParameter("Use --json with -o/--output.")
+        else:
+            render_report(report, explain=explain)
+    except ValueError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1)
+    except typer.Exit:
+        raise
+    except Exception as exc:
+        typer.echo(f"ReconAx error: {exc}", err=True)
+        raise typer.Exit(code=1)
+    finally:
+        recon.close()
+
+
+def _standard_options():
+    return
+
+
+@app.command("headers")
+def headers_command(
+    url: str = typer.Argument(...),
+    explain: bool = typer.Option(False, "--explain"),
+    json_output: bool = typer.Option(False, "--json"),
+    timeout: float = typer.Option(10.0, "--timeout", min=0.1),
+) -> None:
+    _module_command(url, "headers", explain, json_output, timeout)
+
+
+@app.command("cookies")
+def cookies_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "cookies", explain, json_output, timeout)
+
+
+@app.command("html")
+def html_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "html", explain, json_output, timeout)
+
+
+@app.command("robots")
+def robots_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "robots", explain, json_output, timeout)
+
+
+@app.command("dns")
+def dns_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "dns", explain, json_output, timeout)
+
+
+@app.command("tls")
+def tls_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "tls", explain, json_output, timeout)
+
+
+@app.command("sitemap")
+def sitemap_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "sitemap", explain, json_output, timeout)
+
+
+@app.command("tech")
+def tech_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "tech", explain, json_output, timeout)
+
+
+@app.command("cors")
+def cors_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "cors", explain, json_output, timeout)
+
+
+@app.command("csp")
+def csp_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "csp", explain, json_output, timeout)
+
+
+@app.command("sri")
+def sri_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "sri", explain, json_output, timeout)
+
+
+@app.command("security-txt")
+def security_txt_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "security_txt", explain, json_output, timeout)
+
+
+@app.command("metadata")
+def metadata_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "metadata", explain, json_output, timeout)
+
+
+@app.command("resources")
+def resources_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "resources", explain, json_output, timeout)
+
+
+@app.command("endpoints")
+def endpoints_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "endpoints", explain, json_output, timeout)
+
+
+@app.command("attack-surface")
+def attack_surface_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "attack_surface", explain, json_output, timeout)
+
+
+@app.command("score")
+def score_command(url: str = typer.Argument(...), explain: bool = typer.Option(False, "--explain"), json_output: bool = typer.Option(False, "--json"), timeout: float = typer.Option(10.0, "--timeout", min=0.1)) -> None:
+    _module_command(url, "score", explain, json_output, timeout)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

reconax/context.py

@@ -0,0 +1,163 @@
+"""Shared analysis context for ReconAx."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlparse
+
+from bs4 import BeautifulSoup
+
+from .http_client import HTTPClient
+
+
+@dataclass
+class AnalysisContext:
+    """Shared state and lazy caches for one ReconAx target."""
+
+    url: str
+    timeout: float = 10.0
+    verify_ssl: bool = True
+
+    def __post_init__(self) -> None:
+        self._client = HTTPClient(
+            timeout=self.timeout,
+            verify_ssl=self.verify_ssl,
+        )
+        self._response: Any = None
+        self._soup: BeautifulSoup | None = None
+        self._results: dict[str, Any] = {}
+
+    @property
+    def normalized_url(self) -> str:
+        return self._client.normalize_url(self.url)
+
+    @property
+    def origin(self) -> str:
+        parsed = urlparse(self.url)
+        return f"{parsed.scheme}://{parsed.netloc}"
+
+    def response(self, refresh: bool = False):
+        """Return the cached primary HTTP response."""
+        if self._response is None or refresh:
+            self._response = self._client.fetch(self.normalized_url)
+            self._soup = None
+            self._results.clear()
+        return self._response
+
+    def html(self) -> BeautifulSoup:
+        """Return the lazily parsed primary HTML document."""
+        if self._soup is None:
+            self._soup = BeautifulSoup(self.response().content or "", "lxml")
+        return self._soup
+
+    @property
+    def body(self) -> str:
+        return self.response().content or ""
+
+    @property
+    def response_headers(self) -> dict[str, str]:
+        return self.response().headers
+
+    @property
+    def final_url(self) -> str:
+        return self.response().final_url
+
+    @property
+    def status_code(self) -> int:
+        return self.response().status_code
+
+    def get(self, url: str, **kwargs: Any):
+        """Perform a raw GET for secondary public resources."""
+        return self._client.raw_get(url, **kwargs)
+
+    def _cached_module(self, key: str, module_class: type):
+        if key not in self._results:
+            self._results[key] = module_class(self).analyze()
+        return self._results[key]
+
+    def http_result(self):
+        from .modules.http import HTTPModule
+        return self._cached_module("http", HTTPModule)
+
+    def headers_result(self):
+        from .modules.headers import HeadersModule
+        return self._cached_module("headers", HeadersModule)
+
+    def cookies_result(self):
+        from .modules.cookies import CookiesModule
+        return self._cached_module("cookies", CookiesModule)
+
+    def html_result(self):
+        from .modules.html import HTMLModule
+        return self._cached_module("html", HTMLModule)
+
+    def robots_result(self):
+        from .modules.robots import RobotsModule
+        return self._cached_module("robots", RobotsModule)
+
+    def dns_result(self):
+        from .modules.dns import DNSModule
+        return self._cached_module("dns", DNSModule)
+
+    def tls_result(self):
+        from .modules.tls import TLSModule
+        return self._cached_module("tls", TLSModule)
+
+    def tech_result(self):
+        from .modules.tech import TechModule
+        return self._cached_module("tech", TechModule)
+
+    def sitemap_result(self):
+        from .modules.sitemap import SitemapModule
+        return self._cached_module("sitemap", SitemapModule)
+
+    def cors_result(self):
+        from .modules.cors import CORSModule
+        return self._cached_module("cors", CORSModule)
+
+    def csp_result(self):
+        from .modules.csp import CSPModule
+        return self._cached_module("csp", CSPModule)
+
+    def sri_result(self):
+        from .modules.sri import SRIModule
+        return self._cached_module("sri", SRIModule)
+
+    def security_txt_result(self):
+        from .modules.security_txt import SecurityTxtModule
+        return self._cached_module("security_txt", SecurityTxtModule)
+
+    def metadata_result(self):
+        from .modules.metadata import MetadataModule
+        return self._cached_module("metadata", MetadataModule)
+
+    def resources_result(self):
+        from .modules.resources import ResourcesModule
+        return self._cached_module("resources", ResourcesModule)
+
+    def endpoints_result(self):
+        from .modules.endpoints import EndpointsModule
+        return self._cached_module("endpoints", EndpointsModule)
+
+    def attack_surface_result(self):
+        from .modules.attack_surface import AttackSurfaceModule
+        return self._cached_module("attack_surface", AttackSurfaceModule)
+
+    def score_result(self):
+        from .modules.score import ScoreModule
+        return self._cached_module("score", ScoreModule)
+
+    def clear_cache(self) -> None:
+        self._response = None
+        self._soup = None
+        self._results.clear()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "AnalysisContext":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()

reconax/core.py

@@ -0,0 +1,120 @@
+"""High-level ReconAx API."""
+
+from __future__ import annotations
+
+from .context import AnalysisContext
+from .models import ReconReport
+
+
+class ReconAx:
+    """Main public interface for ReconAx analysis."""
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        timeout: float = 10.0,
+        verify_ssl: bool = True,
+    ) -> None:
+        self.context = AnalysisContext(
+            url=url,
+            timeout=timeout,
+            verify_ssl=verify_ssl,
+        )
+
+    @property
+    def url(self) -> str:
+        return self.context.url
+
+    @property
+    def normalized_url(self) -> str:
+        return self.context.normalized_url
+
+    def http(self):
+        return self.context.http_result()
+
+    def headers(self):
+        return self.context.headers_result()
+
+    def cookies(self):
+        return self.context.cookies_result()
+
+    def html(self):
+        return self.context.html_result()
+
+    def robots(self):
+        return self.context.robots_result()
+
+    def dns(self):
+        return self.context.dns_result()
+
+    def tls(self):
+        return self.context.tls_result()
+
+    def tech(self):
+        return self.context.tech_result()
+
+    def sitemap(self):
+        return self.context.sitemap_result()
+
+    def cors(self):
+        return self.context.cors_result()
+
+    def csp(self):
+        return self.context.csp_result()
+
+    def sri(self):
+        return self.context.sri_result()
+
+    def security_txt(self):
+        return self.context.security_txt_result()
+
+    def metadata(self):
+        return self.context.metadata_result()
+
+    def resources(self):
+        return self.context.resources_result()
+
+    def endpoints(self):
+        return self.context.endpoints_result()
+
+    def attack_surface(self):
+        return self.context.attack_surface_result()
+
+    def score(self):
+        return self.context.score_result()
+
+    def analyze(self, *, include_dns: bool = True) -> ReconReport:
+        """Run the complete passive analysis using shared module caches."""
+        report = ReconReport(
+            target=self.url,
+            normalized_url=self.normalized_url,
+            http=self.http(),
+            headers=self.headers(),
+            cookies=self.cookies(),
+            html=self.html(),
+            robots=self.robots(),
+            dns=self.dns() if include_dns else None,
+            tls=self.tls(),
+            tech=self.tech(),
+            sitemap=self.sitemap(),
+            cors=self.cors(),
+            csp=self.csp(),
+            sri=self.sri(),
+            security_txt=self.security_txt(),
+            metadata=self.metadata(),
+            resources=self.resources(),
+            endpoints=self.endpoints(),
+            attack_surface=self.attack_surface(),
+            score=self.score(),
+        )
+        return report
+
+    def close(self) -> None:
+        self.context.close()
+
+    def __enter__(self) -> "ReconAx":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()

reconax/formatters/__init__.py

@@ -0,0 +1,27 @@
+"""
+Output formatters for ReconAx.
+
+Formatters convert structured ReconAx results into human-friendly
+terminal output or machine-readable JSON.
+"""
+
+from .json_out import (
+    report_to_dict,
+    report_to_json,
+    result_to_dict,
+    result_to_json,
+)
+
+from .rich_out import (
+    render_report,
+    render_result,
+)
+
+__all__ = [
+    "report_to_dict",
+    "report_to_json",
+    "result_to_dict",
+    "result_to_json",
+    "render_report",
+    "render_result",
+]

reconax/formatters/json_out.py

@@ -0,0 +1,69 @@
+"""JSON output formatter for ReconAx."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, is_dataclass
+from typing import Any
+
+
+def _serialize(value: Any) -> Any:
+    """Recursively convert ReconAx objects into JSON-compatible values."""
+    if hasattr(value, "to_dict") and callable(value.to_dict):
+        return _serialize(value.to_dict())
+
+    if is_dataclass(value):
+        return {
+            key: _serialize(item)
+            for key, item in asdict(value).items()
+        }
+
+    if isinstance(value, dict):
+        return {str(key): _serialize(item) for key, item in value.items()}
+
+    if isinstance(value, (list, tuple, set)):
+        return [_serialize(item) for item in value]
+
+    if hasattr(value, "value"):
+        try:
+            return value.value
+        except Exception:
+            pass
+
+    return value
+
+
+def result_to_dict(result: Any) -> dict[str, Any]:
+    serialized = _serialize(result)
+    return serialized if isinstance(serialized, dict) else {"result": serialized}
+
+
+def result_to_json(result: Any, *, indent: int = 2) -> str:
+    return json.dumps(
+        result_to_dict(result),
+        indent=indent,
+        ensure_ascii=False,
+        sort_keys=False,
+        default=str,
+    )
+
+
+def report_to_dict(report: Any) -> dict[str, Any]:
+    return result_to_dict(report)
+
+
+def report_to_json(report: Any, *, indent: int = 2) -> str:
+    return json.dumps(
+        report_to_dict(report),
+        indent=indent,
+        ensure_ascii=False,
+        sort_keys=False,
+        default=str,
+    )
+
+
+def write_json(data: Any, filename: str, *, indent: int = 2) -> None:
+    payload = _serialize(data)
+    with open(filename, "w", encoding="utf-8") as file:
+        json.dump(payload, file, indent=indent, ensure_ascii=False, default=str)
+        file.write("\n")