openosint 1.0.0__py3-none-any.whl

openosint/__init__.py

@@ -0,0 +1,5 @@
+"""OpenOSINT — AI-powered Open Source Intelligence agent."""
+
+__version__ = "1.0.0"
+__author__ = "OpenOSINT Contributors"
+__license__ = "MIT"

openosint/agent.py

@@ -0,0 +1,276 @@
+"""OpenOSINT AI agent — Anthropic native tool use loop."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import anthropic
+
+from .config import Config
+from .display import Display
+from .tools.registry import TOOL_DEFINITIONS, execute_tool
+
+SYSTEM_PROMPT = """You are OpenOSINT, an elite AI-powered Open Source Intelligence agent built for
+security researchers, journalists, and investigators.
+
+Your mission: conduct thorough, methodical OSINT investigations using only publicly available
+information.
+
+## Investigation Protocol
+
+When given a target, follow this sequence:
+
+1. **Identify** — Determine what type of target this is (email, username, domain, IP, phone,
+   person name, or compound).
+2. **Pivot** — Start with the most specific tool for the target type, then pivot on findings:
+   - An email → check_email → extract domain → check_domain → check username variants
+     → check_username
+   - A domain → check_domain + dns_lookup (TXT for SPF/DMARC) + whois_lookup → check IPs found
+   - A username → check_username → note platforms found → check email patterns → generate_dorks
+   - An IP → check_ip → reverse DNS → check that domain
+   - A phone → check_phone → generate_dorks
+3. **Cross-reference** — Use results from one tool to inform calls to other tools.
+4. **Dorks** — Always generate_dorks as part of every investigation.
+5. **Breach check** — Always attempt check_breach for any email found (even if no HIBP key,
+   the model will note it).
+6. **Report** — After exhausting relevant tools, compile the final intelligence report.
+
+## Final Report Format
+
+Always end with a structured report using this exact markdown structure:
+
+---
+
+## Target Overview
+Brief description of the target and investigation scope.
+
+## Digital Footprint
+Summary of online presence found.
+
+## Account Discovery
+List of confirmed accounts/profiles with URLs.
+
+## Breach Exposure
+Breach and paste findings.
+
+## Technical Infrastructure
+Domain, DNS, IP, SSL findings (if applicable).
+
+## OSINT Assessment
+Confidence levels, data quality, and key findings summary.
+
+## Recommended Next Steps
+3–5 specific, actionable next investigation steps.
+
+---
+
+## Principles
+- Note confidence (HIGH / MEDIUM / LOW) for key findings.
+- Distinguish confirmed vs inferred data.
+- Flag sensitive findings (GPS coordinates, PII) appropriately.
+- Be concise but complete — this report may be read by lawyers, editors, or executives.
+- You operate within legal and ethical bounds: public data only, no deception.
+"""
+
+
+class OpenOSINTAgent:
+    def __init__(self, config: Config, display: Display) -> None:
+        self.config = config
+        self.display = display
+        self._setup_client()
+        self.messages: list[dict[str, Any]] = []
+        self.investigation_log: list[dict[str, Any]] = []
+
+    def _setup_client(self) -> None:
+        if self.config.provider == "anthropic":
+            self.client: Any = anthropic.Anthropic(api_key=self.config.anthropic_api_key)
+        elif self.config.provider == "openai":
+            import openai as _openai
+            self.client = _openai.OpenAI(api_key=self.config.openai_api_key)
+        elif self.config.provider == "ollama":
+            import openai as _openai
+            self.client = _openai.OpenAI(
+                base_url=f"{self.config.ollama_base_url}/v1",
+                api_key="ollama",
+            )
+        else:
+            raise ValueError(f"Unknown provider: {self.config.provider!r}")
+
+    def investigate(self, target: str) -> str:
+        """Run a full OSINT investigation on the target. Returns the final report."""
+        self.messages = [
+            {
+                "role": "user",
+                "content": (
+                    f"Investigate this target: {target}\n\n"
+                    "Conduct a thorough OSINT investigation using all relevant tools. "
+                    "Follow the investigation protocol, cross-reference findings, and "
+                    "compile a complete intelligence report."
+                ),
+            }
+        ]
+        self.investigation_log = []
+        return self._run_loop()
+
+    def chat(self, user_message: str) -> str:
+        """Send a message in an ongoing investigation session."""
+        self.messages.append({"role": "user", "content": user_message})
+        return self._run_loop()
+
+    def reset(self) -> None:
+        self.messages = []
+        self.investigation_log = []
+
+    def _run_loop(self) -> str:
+        for iteration in range(self.config.max_iterations):
+            try:
+                with self.display.thinking(
+                    f"[dim]Iteration {iteration + 1} — thinking...[/]"
+                    if iteration > 0
+                    else "Analyzing target..."
+                ):
+                    response = self._call_api()
+            except Exception as e:
+                err = str(e)
+                if "401" in err or "authentication" in err.lower() or "api_key" in err.lower():
+                    raise RuntimeError(f"Authentication failed — check your API key.\n{e}") from e
+                if "429" in err or "rate_limit" in err.lower():
+                    raise RuntimeError(f"Rate limit hit — wait a moment and retry.\n{e}") from e
+                raise
+
+            if self.config.provider == "anthropic":
+                return self._handle_anthropic_response(response)
+            else:
+                return self._handle_openai_response(response)
+
+        return "Investigation complete (maximum iterations reached)."
+
+    def _call_api(self) -> Any:
+        if self.config.provider == "anthropic":
+            return self.client.messages.create(
+                model=self.config.model,
+                max_tokens=self.config.max_tokens,
+                system=SYSTEM_PROMPT,
+                tools=TOOL_DEFINITIONS,
+                messages=self.messages,
+            )
+        else:
+            # OpenAI / Ollama compatible path
+            tools_openai = _convert_tools_for_openai(TOOL_DEFINITIONS)
+            return self.client.chat.completions.create(
+                model=self.config.model,
+                max_tokens=self.config.max_tokens,
+                messages=[{"role": "system", "content": SYSTEM_PROMPT}] + self.messages,
+                tools=tools_openai,
+                tool_choice="auto",
+            )
+
+    def _handle_anthropic_response(self, response: Any) -> str:
+        """Handle Anthropic API response in the tool-use loop."""
+        self.messages.append({"role": "assistant", "content": response.content})
+
+        if response.stop_reason == "end_turn":
+            for block in response.content:
+                if hasattr(block, "text"):
+                    return block.text
+            return ""
+
+        if response.stop_reason == "tool_use":
+            tool_results: list[dict[str, Any]] = []
+
+            for block in response.content:
+                if block.type == "tool_use":
+                    self.display.tool_call(block.name, block.input)
+
+                    with self.display.thinking(f"Running {block.name}..."):
+                        result = execute_tool(block.name, block.input, self.config)
+
+                    self.display.tool_result_brief(block.name, result)
+
+                    self.investigation_log.append(
+                        {"tool": block.name, "input": block.input, "result": result}
+                    )
+
+                    tool_results.append(
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": block.id,
+                            "content": json.dumps(result, default=str),
+                        }
+                    )
+
+            self.messages.append({"role": "user", "content": tool_results})
+            return self._run_loop()
+
+        # Unexpected stop reason — return whatever text we have
+        for block in response.content:
+            if hasattr(block, "text"):
+                return block.text
+        return ""
+
+    def _handle_openai_response(self, response: Any) -> str:
+        """Handle OpenAI-compatible API response in the tool-use loop."""
+        msg = response.choices[0].message
+        self.messages.append(
+            {"role": "assistant", "content": msg.content or "", "tool_calls": msg.tool_calls}
+        )
+
+        if not msg.tool_calls:
+            return msg.content or ""
+
+        for tc in msg.tool_calls:
+            fn_name = tc.function.name
+            fn_args = json.loads(tc.function.arguments)
+
+            self.display.tool_call(fn_name, fn_args)
+
+            with self.display.thinking(f"Running {fn_name}..."):
+                result = execute_tool(fn_name, fn_args, self.config)
+
+            self.display.tool_result_brief(fn_name, result)
+            self.investigation_log.append({"tool": fn_name, "input": fn_args, "result": result})
+
+            self.messages.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": tc.id,
+                    "content": json.dumps(result, default=str),
+                }
+            )
+
+        return self._run_loop()
+
+    def save_report(self, report_text: str, target: str) -> Path:
+        """Save the investigation report to a file."""
+        reports_dir = Path(self.config.reports_dir)
+        reports_dir.mkdir(exist_ok=True)
+
+        safe_target = "".join(c if c.isalnum() or c in "-_." else "_" for c in target)[:50]
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        path = reports_dir / f"report_{safe_target}_{timestamp}.md"
+
+        header = (
+            f"# OpenOSINT Investigation Report\n\n"
+            f"**Target:** `{target}`  \n"
+            f"**Date:** {datetime.now().isoformat()}  \n"
+            f"**Model:** {self.config.model}  \n\n---\n\n"
+        )
+        path.write_text(header + report_text, encoding="utf-8")
+        return path
+
+
+def _convert_tools_for_openai(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": t["name"],
+                "description": t["description"],
+                "parameters": t["input_schema"],
+            },
+        }
+        for t in tools
+    ]

openosint/cli.py

@@ -0,0 +1,272 @@
+"""OpenOSINT CLI entry point."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from . import __version__
+from .agent import OpenOSINTAgent
+from .config import CONFIG_FILE, PROVIDER_MODELS, Config
+from .display import Display
+
+
+def _check_disclaimer(config: "Config", display: "Display") -> None:
+    """Show the legal disclaimer on first run; exit if not accepted."""
+    if config.disclaimer_accepted:
+        return
+    accepted = display.show_disclaimer_banner()
+    if not accepted:
+        display.warn("You must accept the disclaimer to use OpenOSINT.")
+        sys.exit(0)
+    config.disclaimer_accepted = True
+    config.save()
+
+
+HELP_TEXT = """
+[bold bright_cyan]Commands available in interactive mode:[/]
+
+  [cyan]investigate[/] <target>   Run an investigation (or just type the target)
+  [cyan]clear[/]                  Clear conversation history
+  [cyan]save[/]                   Save the last report to file
+  [cyan]help[/]                   Show this help
+  [cyan]quit[/] / [cyan]exit[/]            Exit OpenOSINT
+
+[bold bright_cyan]Examples:[/]
+
+  [dim]openosint ❯[/] john.doe@gmail.com
+  [dim]openosint ❯[/] investigate @johndoe
+  [dim]openosint ❯[/] 8.8.8.8
+  [dim]openosint ❯[/] example.com
+  [dim]openosint ❯[/] +1 555 867 5309
+"""
+
+
+@click.group(invoke_without_command=True, context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, "-V", "--version", prog_name="OpenOSINT")
+@click.option("--quiet", "-q", is_flag=True, help="Suppress banner")
+@click.pass_context
+def cli(ctx: click.Context, quiet: bool) -> None:
+    """OpenOSINT — AI-powered Open Source Intelligence agent."""
+    ctx.ensure_object(dict)
+    ctx.obj["quiet"] = quiet
+
+    if ctx.invoked_subcommand is None:
+        _interactive_mode(quiet=quiet)
+
+
+@cli.command()
+@click.argument("target")
+@click.option("--save", "-s", is_flag=True, help="Save report to file")
+@click.option("--output", "-o", type=click.Path(), help="Output file path (implies --save)")
+@click.option("--quiet", "-q", is_flag=True, help="Suppress banner")
+def investigate(target: str, save: bool, output: Optional[str], quiet: bool) -> None:
+    """Investigate a target and produce an intelligence report.
+
+    TARGET can be an email, username, domain, IP address, or phone number.
+
+    \b
+    Examples:
+      openosint investigate john@example.com
+      openosint investigate example.com --save
+      openosint investigate 8.8.8.8
+    """
+    display = Display(quiet=quiet)
+    if not quiet:
+        display.banner(__version__)
+
+    config = Config.load()
+    _check_disclaimer(config, display)
+    errors = config.validate()
+    if errors:
+        for err in errors:
+            display.error(err)
+        display.info("Run [bright_cyan]openosint config[/] to set up your API keys.")
+        sys.exit(1)
+
+    agent = OpenOSINTAgent(config, display)
+    display.investigation_start(target)
+
+    try:
+        report = agent.investigate(target)
+    except RuntimeError as e:
+        display.error(str(e))
+        sys.exit(1)
+    except KeyboardInterrupt:
+        display.print()
+        display.info("Investigation interrupted.")
+        sys.exit(0)
+
+    display.final_report(report, target)
+
+    if save or output:
+        if output:
+            path = Path(output)
+            header = f"# OpenOSINT Investigation Report\n\n**Target:** `{target}`\n\n---\n\n"
+            path.write_text(header + report, encoding="utf-8")
+            display.success(f"Report saved to [cyan]{path}[/]")
+        else:
+            path = agent.save_report(report, target)
+            display.success(f"Report saved to [cyan]{path}[/]")
+
+
+@cli.command()
+@click.option(
+    "--provider",
+    type=click.Choice(["anthropic", "openai", "ollama"]),
+    help="AI provider",
+)
+@click.option("--model", help="Model name override")
+@click.option("--show", is_flag=True, help="Show current configuration")
+def config(provider: Optional[str], model: Optional[str], show: bool) -> None:
+    """Configure OpenOSINT: provider, model, and API keys.
+
+    API keys are read from environment variables or .env file:
+
+    \b
+      ANTHROPIC_API_KEY   — for Anthropic (default provider)
+      OPENAI_API_KEY      — for OpenAI
+      HIBP_API_KEY        — for HaveIBeenPwned breach checks
+      ABUSEIPDB_API_KEY   — for IP reputation checks
+    """
+    display = Display()
+    cfg = Config.load()
+
+    if show or (not provider and not model):
+        display.config_table(
+            {
+                "provider": cfg.provider,
+                "model": cfg.model,
+                "anthropic_api_key": cfg.anthropic_api_key,
+                "openai_api_key": cfg.openai_api_key,
+                "hibp_api_key": cfg.hibp_api_key,
+                "abuseipdb_api_key": cfg.abuseipdb_api_key,
+                "config_file": str(CONFIG_FILE),
+                "max_tokens": cfg.max_tokens,
+                "max_iterations": cfg.max_iterations,
+                "save_reports": cfg.save_reports,
+                "reports_dir": cfg.reports_dir,
+            }
+        )
+        display.info("Set API keys via environment variables or [cyan].env[/] file.")
+        return
+
+    if provider:
+        cfg.provider = provider  # type: ignore[assignment]
+        if not model:
+            cfg.model = PROVIDER_MODELS.get(provider, cfg.model)
+        display.success(f"Provider set to [cyan]{provider}[/]")
+
+    if model:
+        cfg.model = model
+        display.success(f"Model set to [cyan]{model}[/]")
+
+    cfg.save()
+    display.success(f"Configuration saved to [cyan]{CONFIG_FILE}[/]")
+
+
+@cli.command()
+def version() -> None:
+    """Print version information."""
+    display = Display()
+    display.print(f"[bold bright_cyan]OpenOSINT[/] [dim]v{__version__}[/]")
+
+
+def _interactive_mode(quiet: bool = False) -> None:
+    """Interactive chat-style investigation session."""
+    display = Display(quiet=quiet)
+    if not quiet:
+        display.banner(__version__)
+
+    config = Config.load()
+    _check_disclaimer(config, display)
+    errors = config.validate()
+    if errors:
+        for err in errors:
+            display.error(err)
+        display.warn("Set [cyan]ANTHROPIC_API_KEY[/] in your environment or [cyan].env[/] file.")
+        display.warn("Run [cyan]openosint config --show[/] for current settings.")
+        sys.exit(1)
+
+    display.info(f"Provider: [cyan]{config.provider}[/]  Model: [cyan]{config.model}[/]")
+    display.info(
+        "Type a target to investigate, or [cyan]help[/] for commands. "
+        "[cyan]Ctrl-C[/] or [cyan]quit[/] to exit."
+    )
+    display.print()
+
+    agent = OpenOSINTAgent(config, display)
+    last_report: Optional[str] = None
+
+    while True:
+        try:
+            user_input = display.prompt()
+        except (KeyboardInterrupt, EOFError):
+            display.print()
+            display.info("Goodbye.")
+            break
+
+        user_input = user_input.strip()
+        if not user_input:
+            continue
+
+        cmd = user_input.lower()
+
+        if cmd in ("quit", "exit", "q", ":q"):
+            display.info("Goodbye.")
+            break
+
+        elif cmd == "help":
+            display.print(HELP_TEXT)
+
+        elif cmd == "clear":
+            agent.reset()
+            display.success("Conversation cleared.")
+
+        elif cmd == "save":
+            if last_report and agent.messages:
+                target = _extract_target_from_messages(agent.messages)
+                path = agent.save_report(last_report, target or "investigation")
+                display.success(f"Saved to [cyan]{path}[/]")
+            else:
+                display.warn("Nothing to save yet.")
+
+        else:
+            # Strip "investigate " prefix if present
+            target = user_input.removeprefix("investigate ").strip()
+
+            try:
+                if not agent.messages:
+                    display.investigation_start(target)
+                    report = agent.investigate(target)
+                else:
+                    report = agent.chat(user_input)
+            except RuntimeError as e:
+                display.error(str(e))
+                continue
+            except KeyboardInterrupt:
+                display.print()
+                display.info("Investigation interrupted. Continue or type [cyan]quit[/].")
+                continue
+
+            display.final_report(report, target)
+            last_report = report
+
+            if config.save_reports:
+                path = agent.save_report(report, target)
+                display.info(f"Auto-saved to [cyan]{path}[/]")
+
+
+def _extract_target_from_messages(messages: list) -> Optional[str]:
+    for msg in messages:
+        if isinstance(msg, dict) and msg.get("role") == "user":
+            content = msg.get("content", "")
+            if isinstance(content, str) and "Investigate this target:" in content:
+                lines = content.split("\n")
+                for line in lines:
+                    if line.startswith("Investigate this target:"):
+                        return line.replace("Investigate this target:", "").strip()
+    return None

openosint/config.py

@@ -0,0 +1,113 @@
+"""Configuration management for OpenOSINT."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Optional
+
+from dotenv import load_dotenv
+
+CONFIG_DIR = Path.home() / ".config" / "openosint"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+PROVIDER_MODELS: dict[str, str] = {
+    "anthropic": "claude-sonnet-4-20250514",
+    "openai": "gpt-4o",
+    "ollama": "llama3.1",
+}
+
+
+@dataclass
+class Config:
+    provider: Literal["anthropic", "openai", "ollama"] = "anthropic"
+    model: str = ""
+
+    anthropic_api_key: Optional[str] = None
+    openai_api_key: Optional[str] = None
+    hibp_api_key: Optional[str] = None
+    abuseipdb_api_key: Optional[str] = None
+
+    ollama_base_url: str = "http://localhost:11434"
+
+    max_tokens: int = 8192
+    max_iterations: int = 25
+
+    save_reports: bool = True
+    reports_dir: str = "reports"
+
+    disclaimer_accepted: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.model:
+            self.model = PROVIDER_MODELS.get(self.provider, "claude-sonnet-4-20250514")
+
+    @classmethod
+    def load(cls) -> "Config":
+        load_dotenv()
+
+        config = cls()
+
+        if CONFIG_FILE.exists():
+            try:
+                with open(CONFIG_FILE) as f:
+                    data = json.load(f)
+                for key, value in data.items():
+                    if hasattr(config, key):
+                        setattr(config, key, value)
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        # Environment variables always win
+        if v := os.getenv("ANTHROPIC_API_KEY"):
+            config.anthropic_api_key = v
+        if v := os.getenv("OPENAI_API_KEY"):
+            config.openai_api_key = v
+        if v := os.getenv("HIBP_API_KEY"):
+            config.hibp_api_key = v
+        if v := os.getenv("ABUSEIPDB_API_KEY"):
+            config.abuseipdb_api_key = v
+        if v := os.getenv("OPENOSINT_PROVIDER"):
+            config.provider = v  # type: ignore[assignment]
+        if v := os.getenv("OPENOSINT_MODEL"):
+            config.model = v
+        if v := os.getenv("OLLAMA_BASE_URL"):
+            config.ollama_base_url = v
+
+        if not config.model:
+            config.model = PROVIDER_MODELS.get(config.provider, "claude-sonnet-4-20250514")
+
+        return config
+
+    def save(self) -> None:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        data = {
+            "provider": self.provider,
+            "model": self.model,
+            "ollama_base_url": self.ollama_base_url,
+            "max_tokens": self.max_tokens,
+            "max_iterations": self.max_iterations,
+            "save_reports": self.save_reports,
+            "reports_dir": self.reports_dir,
+            "disclaimer_accepted": self.disclaimer_accepted,
+        }
+        with open(CONFIG_FILE, "w") as f:
+            json.dump(data, f, indent=2)
+
+    def validate(self) -> list[str]:
+        errors: list[str] = []
+        if self.provider == "anthropic" and not self.anthropic_api_key:
+            errors.append("ANTHROPIC_API_KEY is not set (export it or add to .env)")
+        elif self.provider == "openai" and not self.openai_api_key:
+            errors.append("OPENAI_API_KEY is not set (export it or add to .env)")
+        return errors
+
+    @property
+    def active_api_key(self) -> Optional[str]:
+        if self.provider == "anthropic":
+            return self.anthropic_api_key
+        if self.provider == "openai":
+            return self.openai_api_key
+        return None