ghspy 0.1.0__tar.gz

ghspy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shazeus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghspy-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: ghspy
+Version: 0.1.0
+Summary: GitHub OSINT tool — extract intelligence from any GitHub user profile
+Author: shazeus
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shazeus/ghspy
+Project-URL: Repository, https://github.com/shazeus/ghspy
+Project-URL: Issues, https://github.com/shazeus/ghspy/issues
+Keywords: github,osint,reconnaissance,cli,security,intelligence
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: rich>=13.0
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">GhSpy</h1>
+  <p align="center">GitHub OSINT tool — extract intelligence from any GitHub user profile.</p>
+  <p align="center">
+    <a href="https://pypi.org/project/ghspy/"><img src="https://img.shields.io/pypi/v/ghspy?color=blue&label=PyPI" alt="PyPI"></a>
+    <a href="https://pypi.org/project/ghspy/"><img src="https://img.shields.io/pypi/pyversions/ghspy" alt="Python"></a>
+    <a href="https://github.com/shazeus/ghspy/blob/main/LICENSE"><img src="https://img.shields.io/github/license/shazeus/ghspy" alt="License"></a>
+    <a href="https://github.com/shazeus/ghspy/stargazers"><img src="https://img.shields.io/github/stars/shazeus/ghspy?style=social" alt="Stars"></a>
+  </p>
+</p>
+
+---
+
+Discover emails, estimate timezones, map tech stacks, find collaborators, and analyze activity patterns — all from your terminal. GhSpy uses the public GitHub API to gather open-source intelligence on any GitHub user.
+
+- **Email Discovery** — extract real email addresses from commit history
+- **Timezone Estimation** — estimate location from commit hour patterns
+- **Activity Analysis** — peak hours, active days, contribution streaks
+- **Tech Stack Mapping** — languages, topics, original vs forked repos
+- **Collaborator Detection** — frequent interactions, orgs, following
+- **Identity Mapping** — cross-reference commit emails and author names
+
+## Installation
+
+```bash
+pip install ghspy
+```
+
+Requires Python 3.8+. Works on Linux, macOS, and Windows.
+
+## Usage
+
+```bash
+# Full OSINT scan
+ghspy scan torvalds
+
+# Extract emails from commit history
+ghspy emails dhh
+
+# Estimate timezone
+ghspy timezone antirez
+
+# Activity patterns
+ghspy activity shazeus
+
+# Tech stack
+ghspy techstack gvanrossum
+
+# Collaborators & organizations
+ghspy collabs octocat
+
+# Export to JSON
+ghspy export torvalds --format json -o report.json
+
+# Export to CSV
+ghspy export torvalds --format csv -o report.csv
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ghspy scan <user>` | Full OSINT scan with all modules |
+| `ghspy emails <user>` | Extract emails from commit history |
+| `ghspy timezone <user>` | Estimate timezone from commit patterns |
+| `ghspy activity <user>` | Activity breakdown by hour, day, and event type |
+| `ghspy techstack <user>` | Languages, topics, and repo statistics |
+| `ghspy collabs <user>` | Collaborators, organizations, and following |
+| `ghspy export <user>` | Export findings to JSON or CSV |
+| `ghspy rate-limit` | Check GitHub API rate limit |
+
+## Configuration
+
+### GitHub Token
+
+Without a token you get **60 requests/hour**. With a token you get **5,000 requests/hour**. A full scan uses 20–50 requests depending on the user's repo count.
+
+```bash
+# Set as environment variable (recommended)
+export GITHUB_TOKEN=ghp_your_token_here
+
+# Or pass directly
+ghspy --token ghp_xxxx scan torvalds
+```
+
+Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens) — no special scopes needed for public data.
+
+### JSON Output
+
+Every command supports `--json-output` for piping to other tools:
+
+```bash
+ghspy scan user --json-output | jq '.emails'
+ghspy scan user --json-output | jq '.timezone.estimated_timezone'
+```
+
+## How It Works
+
+GhSpy queries the public GitHub REST API to collect:
+
+1. **User profile** — public info, bio, location, social links
+2. **Repositories** — languages, topics, fork status, activity dates
+3. **Commit history** — author emails, timestamps, committer info
+4. **Public events** — pushes, PRs, issues, comments
+5. **Social graph** — followers, following, organizations
+
+All data is publicly available through GitHub's API. No authentication bypass or scraping is involved.
+
+## Disclaimer
+
+This tool only accesses **publicly available data** through the official GitHub API. It does not bypass access controls, scrape private information, or violate GitHub's Terms of Service. Use responsibly.
+
+## License
+
+[MIT](LICENSE)

ghspy-0.1.0/README.md

@@ -0,0 +1,115 @@
+<p align="center">
+  <h1 align="center">GhSpy</h1>
+  <p align="center">GitHub OSINT tool — extract intelligence from any GitHub user profile.</p>
+  <p align="center">
+    <a href="https://pypi.org/project/ghspy/"><img src="https://img.shields.io/pypi/v/ghspy?color=blue&label=PyPI" alt="PyPI"></a>
+    <a href="https://pypi.org/project/ghspy/"><img src="https://img.shields.io/pypi/pyversions/ghspy" alt="Python"></a>
+    <a href="https://github.com/shazeus/ghspy/blob/main/LICENSE"><img src="https://img.shields.io/github/license/shazeus/ghspy" alt="License"></a>
+    <a href="https://github.com/shazeus/ghspy/stargazers"><img src="https://img.shields.io/github/stars/shazeus/ghspy?style=social" alt="Stars"></a>
+  </p>
+</p>
+
+---
+
+Discover emails, estimate timezones, map tech stacks, find collaborators, and analyze activity patterns — all from your terminal. GhSpy uses the public GitHub API to gather open-source intelligence on any GitHub user.
+
+- **Email Discovery** — extract real email addresses from commit history
+- **Timezone Estimation** — estimate location from commit hour patterns
+- **Activity Analysis** — peak hours, active days, contribution streaks
+- **Tech Stack Mapping** — languages, topics, original vs forked repos
+- **Collaborator Detection** — frequent interactions, orgs, following
+- **Identity Mapping** — cross-reference commit emails and author names
+
+## Installation
+
+```bash
+pip install ghspy
+```
+
+Requires Python 3.8+. Works on Linux, macOS, and Windows.
+
+## Usage
+
+```bash
+# Full OSINT scan
+ghspy scan torvalds
+
+# Extract emails from commit history
+ghspy emails dhh
+
+# Estimate timezone
+ghspy timezone antirez
+
+# Activity patterns
+ghspy activity shazeus
+
+# Tech stack
+ghspy techstack gvanrossum
+
+# Collaborators & organizations
+ghspy collabs octocat
+
+# Export to JSON
+ghspy export torvalds --format json -o report.json
+
+# Export to CSV
+ghspy export torvalds --format csv -o report.csv
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ghspy scan <user>` | Full OSINT scan with all modules |
+| `ghspy emails <user>` | Extract emails from commit history |
+| `ghspy timezone <user>` | Estimate timezone from commit patterns |
+| `ghspy activity <user>` | Activity breakdown by hour, day, and event type |
+| `ghspy techstack <user>` | Languages, topics, and repo statistics |
+| `ghspy collabs <user>` | Collaborators, organizations, and following |
+| `ghspy export <user>` | Export findings to JSON or CSV |
+| `ghspy rate-limit` | Check GitHub API rate limit |
+
+## Configuration
+
+### GitHub Token
+
+Without a token you get **60 requests/hour**. With a token you get **5,000 requests/hour**. A full scan uses 20–50 requests depending on the user's repo count.
+
+```bash
+# Set as environment variable (recommended)
+export GITHUB_TOKEN=ghp_your_token_here
+
+# Or pass directly
+ghspy --token ghp_xxxx scan torvalds
+```
+
+Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens) — no special scopes needed for public data.
+
+### JSON Output
+
+Every command supports `--json-output` for piping to other tools:
+
+```bash
+ghspy scan user --json-output | jq '.emails'
+ghspy scan user --json-output | jq '.timezone.estimated_timezone'
+```
+
+## How It Works
+
+GhSpy queries the public GitHub REST API to collect:
+
+1. **User profile** — public info, bio, location, social links
+2. **Repositories** — languages, topics, fork status, activity dates
+3. **Commit history** — author emails, timestamps, committer info
+4. **Public events** — pushes, PRs, issues, comments
+5. **Social graph** — followers, following, organizations
+
+All data is publicly available through GitHub's API. No authentication bypass or scraping is involved.
+
+## Disclaimer
+
+This tool only accesses **publicly available data** through the official GitHub API. It does not bypass access controls, scrape private information, or violate GitHub's Terms of Service. Use responsibly.
+
+## License
+
+[MIT](LICENSE)

ghspy-0.1.0/ghspy/__init__.py

@@ -0,0 +1,3 @@
+"""GitSpy - GitHub OSINT Tool."""
+
+__version__ = "0.1.0"

ghspy-0.1.0/ghspy/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m ghspy."""
+
+from ghspy.cli import cli
+
+if __name__ == "__main__":
+    cli()

ghspy-0.1.0/ghspy/analyzer.py

@@ -0,0 +1,305 @@
+"""OSINT analysis logic for GitSpy."""
+
+from collections import Counter, defaultdict
+from datetime import datetime, timezone
+import re
+
+
+class UserAnalyzer:
+    def __init__(self, client, username):
+        self.client = client
+        self.username = username
+        self._user = None
+        self._repos = None
+        self._events = None
+
+    @property
+    def user(self):
+        if self._user is None:
+            self._user = self.client.get_user(self.username)
+        return self._user
+
+    @property
+    def repos(self):
+        if self._repos is None:
+            self._repos = self.client.get_repos(self.username)
+        return self._repos
+
+    @property
+    def events(self):
+        if self._events is None:
+            self._events = self.client.get_events(self.username)
+        return self._events
+
+    def profile_info(self):
+        u = self.user
+        return {
+            "login": u["login"],
+            "name": u.get("name") or "N/A",
+            "bio": u.get("bio") or "N/A",
+            "company": u.get("company") or "N/A",
+            "location": u.get("location") or "N/A",
+            "email": u.get("email") or "N/A",
+            "blog": u.get("blog") or "N/A",
+            "twitter": u.get("twitter_username") or "N/A",
+            "public_repos": u["public_repos"],
+            "public_gists": u["public_gists"],
+            "followers": u["followers"],
+            "following": u["following"],
+            "created_at": u["created_at"],
+            "updated_at": u["updated_at"],
+            "avatar": u["avatar_url"],
+            "profile": u["html_url"],
+            "hireable": u.get("hireable"),
+        }
+
+    def extract_emails(self):
+        emails = set()
+        profile_email = self.user.get("email")
+        if profile_email:
+            emails.add(profile_email)
+
+        for repo in self.repos[:10]:
+            owner = repo["owner"]["login"]
+            name = repo["name"]
+            if repo.get("fork"):
+                continue
+            try:
+                commits = self.client.get_repo_commits(owner, name, author=self.username, max_pages=1)
+                for c in commits[:20]:
+                    commit_data = c.get("commit", {})
+                    author = commit_data.get("author", {})
+                    committer = commit_data.get("committer", {})
+                    if author.get("email") and not self._is_noreply(author["email"]):
+                        emails.add(author["email"])
+                    if committer.get("email") and not self._is_noreply(committer["email"]):
+                        emails.add(committer["email"])
+            except Exception:
+                continue
+
+        return sorted(emails)
+
+    def _is_noreply(self, email):
+        noreply_patterns = ["noreply", "users.noreply.github.com"]
+        return any(p in email.lower() for p in noreply_patterns)
+
+    def estimate_timezone(self):
+        hours = []
+        for repo in self.repos[:8]:
+            if repo.get("fork"):
+                continue
+            try:
+                commits = self.client.get_repo_commits(
+                    repo["owner"]["login"], repo["name"],
+                    author=self.username, max_pages=1
+                )
+                for c in commits[:30]:
+                    date_str = c.get("commit", {}).get("author", {}).get("date", "")
+                    if date_str:
+                        dt = datetime.fromisoformat(date_str.replace("Z", "+00:00"))
+                        hours.append(dt.hour)
+            except Exception:
+                continue
+
+        if not hours:
+            return {"estimated_utc_offset": None, "confidence": "none", "peak_hours_utc": []}
+
+        hour_counts = Counter(hours)
+        peak_hours = [h for h, _ in hour_counts.most_common(5)]
+
+        avg_peak = sum(peak_hours) / len(peak_hours)
+        if 6 <= avg_peak <= 10:
+            offset = 0
+            tz_guess = "UTC+0 (UK/Portugal/West Africa)"
+        elif 10 < avg_peak <= 14:
+            offset = -(avg_peak - 9)
+            tz_guess = f"UTC{int(offset):+d} (US East / Americas)"
+        elif 14 < avg_peak <= 18:
+            offset = -(avg_peak - 9)
+            tz_guess = f"UTC{int(offset):+d} (US West / Pacific)"
+        elif avg_peak > 18 or avg_peak < 3:
+            offset = 24 - avg_peak + 9 if avg_peak > 18 else 9 - avg_peak
+            tz_guess = f"UTC+{int(offset)} (Asia / Eastern)"
+        else:
+            offset = 9 - avg_peak
+            tz_guess = f"UTC+{int(offset):+d} (Europe)"
+
+        total_commits = len(hours)
+        if total_commits > 50:
+            confidence = "high"
+        elif total_commits > 20:
+            confidence = "medium"
+        else:
+            confidence = "low"
+
+        return {
+            "estimated_timezone": tz_guess,
+            "estimated_utc_offset": round(offset),
+            "confidence": confidence,
+            "total_commits_analyzed": total_commits,
+            "peak_hours_utc": sorted(peak_hours),
+            "hour_distribution": dict(sorted(hour_counts.items())),
+        }
+
+    def activity_patterns(self):
+        hours = []
+        days = []
+        dates = []
+
+        for event in self.events:
+            date_str = event.get("created_at", "")
+            if date_str:
+                dt = datetime.fromisoformat(date_str.replace("Z", "+00:00"))
+                hours.append(dt.hour)
+                days.append(dt.strftime("%A"))
+                dates.append(dt.date())
+
+        for repo in self.repos[:5]:
+            if repo.get("fork"):
+                continue
+            try:
+                commits = self.client.get_repo_commits(
+                    repo["owner"]["login"], repo["name"],
+                    author=self.username, max_pages=1
+                )
+                for c in commits[:20]:
+                    date_str = c.get("commit", {}).get("author", {}).get("date", "")
+                    if date_str:
+                        dt = datetime.fromisoformat(date_str.replace("Z", "+00:00"))
+                        hours.append(dt.hour)
+                        days.append(dt.strftime("%A"))
+                        dates.append(dt.date())
+            except Exception:
+                continue
+
+        hour_counts = Counter(hours)
+        day_counts = Counter(days)
+
+        day_order = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
+        sorted_days = {d: day_counts.get(d, 0) for d in day_order}
+
+        streak = 0
+        if dates:
+            unique_days = sorted(set(dates), reverse=True)
+            streak = 1
+            for i in range(1, len(unique_days)):
+                if (unique_days[i - 1] - unique_days[i]).days == 1:
+                    streak += 1
+                else:
+                    break
+
+        event_types = Counter(e.get("type", "Unknown") for e in self.events)
+
+        return {
+            "total_events": len(self.events),
+            "by_hour": dict(sorted(hour_counts.items())),
+            "by_day": sorted_days,
+            "streak": streak,
+            "event_types": dict(event_types.most_common(10)),
+            "first_activity": min(dates).isoformat() if dates else None,
+            "last_activity": max(dates).isoformat() if dates else None,
+        }
+
+    def tech_stack(self):
+        languages = Counter()
+        topics = Counter()
+        all_deps = set()
+
+        for repo in self.repos:
+            if repo.get("fork"):
+                continue
+            lang = repo.get("language")
+            if lang:
+                languages[lang] += 1
+            for topic in repo.get("topics", []):
+                topics[topic] += 1
+
+        return {
+            "languages": dict(languages.most_common(15)),
+            "topics": dict(topics.most_common(20)),
+            "total_repos": len(self.repos),
+            "original_repos": sum(1 for r in self.repos if not r.get("fork")),
+            "forked_repos": sum(1 for r in self.repos if r.get("fork")),
+        }
+
+    def find_collaborators(self):
+        collaborators = Counter()
+
+        for event in self.events:
+            payload = event.get("payload", {})
+            if event["type"] == "PullRequestEvent":
+                pr = payload.get("pull_request", {})
+                user = pr.get("user", {}).get("login")
+                if user and user != self.username:
+                    collaborators[user] += 1
+                merged_by = pr.get("merged_by", {})
+                if merged_by:
+                    merger = merged_by.get("login")
+                    if merger and merger != self.username:
+                        collaborators[merger] += 1
+
+            if event["type"] == "IssueCommentEvent":
+                issue = payload.get("issue", {})
+                user = issue.get("user", {}).get("login")
+                if user and user != self.username:
+                    collaborators[user] += 1
+
+        orgs = self.client.get_orgs(self.username)
+        org_names = [o["login"] for o in orgs]
+
+        following = self.client.get_following(self.username)
+        following_names = [f["login"] for f in following[:50]]
+
+        return {
+            "frequent_collaborators": dict(collaborators.most_common(15)),
+            "organizations": org_names,
+            "following": following_names[:20],
+            "following_count": len(following),
+        }
+
+    def detect_alt_emails(self):
+        email_to_names = defaultdict(set)
+        name_to_emails = defaultdict(set)
+
+        for repo in self.repos[:10]:
+            if repo.get("fork"):
+                continue
+            try:
+                commits = self.client.get_repo_commits(
+                    repo["owner"]["login"], repo["name"],
+                    author=self.username, max_pages=1,
+                )
+                for c in commits[:20]:
+                    author = c.get("commit", {}).get("author", {})
+                    name = author.get("name", "")
+                    email = author.get("email", "")
+                    if name and email:
+                        email_to_names[email].add(name)
+                        name_to_emails[name].add(email)
+            except Exception:
+                continue
+
+        identities = []
+        for email, names in email_to_names.items():
+            identities.append({
+                "email": email,
+                "names": sorted(names),
+                "is_noreply": self._is_noreply(email),
+            })
+
+        return {
+            "identities": identities,
+            "unique_emails": len(email_to_names),
+            "unique_names": len(name_to_emails),
+        }
+
+    def full_scan(self):
+        return {
+            "profile": self.profile_info(),
+            "emails": self.extract_emails(),
+            "timezone": self.estimate_timezone(),
+            "activity": self.activity_patterns(),
+            "tech_stack": self.tech_stack(),
+            "collaborators": self.find_collaborators(),
+            "identities": self.detect_alt_emails(),
+        }

ghspy-0.1.0/ghspy/cli.py

@@ -0,0 +1,176 @@
+"""CLI interface for GitSpy."""
+
+import json
+
+import click
+from rich.console import Console
+
+from ghspy import __version__
+from ghspy.github_api import GitHubClient
+from ghspy.analyzer import UserAnalyzer
+from ghspy import display
+
+console = Console()
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="ghspy")
+@click.option("--token", envvar="GITHUB_TOKEN", help="GitHub personal access token")
+@click.pass_context
+def cli(ctx, token):
+    """GitSpy - GitHub OSINT tool for user reconnaissance."""
+    ctx.ensure_object(dict)
+    ctx.obj["client"] = GitHubClient(token)
+
+
+@cli.command()
+@click.argument("username")
+@click.option("--json-output", "as_json", is_flag=True, help="Output as JSON")
+@click.pass_context
+def scan(ctx, username, as_json):
+    """Full OSINT scan of a GitHub user."""
+    analyzer = UserAnalyzer(ctx.obj["client"], username)
+
+    if as_json:
+        report = analyzer.full_scan()
+        click.echo(json.dumps(report, indent=2, default=str))
+        return
+
+    display.print_header(username)
+    with console.status(f"[cyan]Scanning @{username}...[/]"):
+        report = analyzer.full_scan()
+    display.print_full_scan(report)
+
+
+@cli.command()
+@click.argument("username")
+@click.pass_context
+def emails(ctx, username):
+    """Extract email addresses from commit history."""
+    analyzer = UserAnalyzer(ctx.obj["client"], username)
+    display.print_header(username)
+    with console.status("[cyan]Extracting emails from commits...[/]"):
+        found = analyzer.extract_emails()
+    display.print_emails(found)
+
+
+@cli.command()
+@click.argument("username")
+@click.pass_context
+def timezone(ctx, username):
+    """Estimate timezone from commit timestamps."""
+    analyzer = UserAnalyzer(ctx.obj["client"], username)
+    display.print_header(username)
+    with console.status("[cyan]Analyzing commit timestamps...[/]"):
+        data = analyzer.estimate_timezone()
+    display.print_timezone(data)
+
+
+@cli.command()
+@click.argument("username")
+@click.pass_context
+def activity(ctx, username):
+    """Show activity patterns and heatmap."""
+    analyzer = UserAnalyzer(ctx.obj["client"], username)
+    display.print_header(username)
+    with console.status("[cyan]Analyzing activity...[/]"):
+        data = analyzer.activity_patterns()
+    display.print_activity(data)
+
+
+@cli.command()
+@click.argument("username")
+@click.pass_context
+def collabs(ctx, username):
+    """List frequent collaborators and organizations."""
+    analyzer = UserAnalyzer(ctx.obj["client"], username)
+    display.print_header(username)
+    with console.status("[cyan]Finding collaborators...[/]"):
+        data = analyzer.find_collaborators()
+    display.print_collaborators(data)
+
+
+@cli.command()
+@click.argument("username")
+@click.pass_context
+def techstack(ctx, username):
+    """Show technology stack from repositories."""
+    analyzer = UserAnalyzer(ctx.obj["client"], username)
+    display.print_header(username)
+    data = analyzer.tech_stack()
+    display.print_tech_stack(data)
+
+
+@cli.command()
+@click.argument("username")
+@click.option("--format", "fmt", type=click.Choice(["json", "csv"]), default="json")
+@click.option("--output", "-o", help="Output file path")
+@click.pass_context
+def export(ctx, username, fmt, output):
+    """Export all findings to JSON or CSV."""
+    analyzer = UserAnalyzer(ctx.obj["client"], username)
+
+    with console.status(f"[cyan]Running full scan on @{username}...[/]"):
+        report = analyzer.full_scan()
+
+    if fmt == "json":
+        content = json.dumps(report, indent=2, default=str)
+        if output:
+            with open(output, "w") as f:
+                f.write(content)
+            console.print(f"[green]Exported to {output}[/]")
+        else:
+            click.echo(content)
+
+    elif fmt == "csv":
+        import csv
+        import io
+
+        out = io.StringIO()
+        writer = csv.writer(out)
+        writer.writerow(["Category", "Key", "Value"])
+
+        profile = report["profile"]
+        for k, v in profile.items():
+            writer.writerow(["profile", k, v])
+
+        for email in report["emails"]:
+            writer.writerow(["email", "address", email])
+
+        tz = report["timezone"]
+        for k, v in tz.items():
+            if k != "hour_distribution":
+                writer.writerow(["timezone", k, v])
+
+        for lang, count in report["tech_stack"]["languages"].items():
+            writer.writerow(["language", lang, count])
+
+        content = out.getvalue()
+        if output:
+            with open(output, "w") as f:
+                f.write(content)
+            console.print(f"[green]Exported to {output}[/]")
+        else:
+            click.echo(content)
+
+
+@cli.command(name="rate-limit")
+@click.pass_context
+def rate_limit(ctx):
+    """Check GitHub API rate limit status."""
+    client = ctx.obj["client"]
+    data = client.get_rate_limit()
+    core = data["resources"]["core"]
+
+    console.print(f"\n[bold]GitHub API Rate Limit[/]")
+    remaining = core["remaining"]
+    limit = core["limit"]
+    color = "green" if remaining > 100 else "red"
+    console.print(f"  Remaining: [{color}]{remaining}[/] / {limit}")
+
+    from datetime import datetime, timezone
+    reset_time = datetime.fromtimestamp(core["reset"], tz=timezone.utc)
+    console.print(f"  Resets at: {reset_time.strftime('%H:%M:%S UTC')}")
+    if not client.token:
+        console.print("  [yellow]Tip: Set GITHUB_TOKEN for 5000 req/hr instead of 60[/]")
+    console.print()

ghspy-0.1.0/ghspy/display.py

@@ -0,0 +1,227 @@
+"""Rich terminal display for GitSpy."""
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich import box
+
+console = Console()
+
+
+def print_header(username):
+    console.print()
+    console.print(
+        Panel(
+            f"[bold cyan]GitSpy[/] — scanning [bold yellow]@{username}[/]",
+            border_style="cyan",
+            padding=(1, 2),
+        )
+    )
+    console.print()
+
+
+def print_profile(data):
+    table = Table(title="Profile", box=box.ROUNDED, border_style="blue")
+    table.add_column("Field", style="bold")
+    table.add_column("Value")
+
+    table.add_row("Username", data["login"])
+    table.add_row("Name", data["name"])
+    table.add_row("Bio", data["bio"])
+    table.add_row("Company", data["company"])
+    table.add_row("Location", data["location"])
+    table.add_row("Email", data["email"])
+    table.add_row("Blog", data["blog"])
+    table.add_row("Twitter", f"@{data['twitter']}" if data["twitter"] != "N/A" else "N/A")
+    table.add_row("Repos", str(data["public_repos"]))
+    table.add_row("Gists", str(data["public_gists"]))
+    table.add_row("Followers", str(data["followers"]))
+    table.add_row("Following", str(data["following"]))
+    table.add_row("Created", data["created_at"][:10])
+    table.add_row("Hireable", str(data["hireable"]) if data["hireable"] is not None else "N/A")
+    table.add_row("Profile", data["profile"])
+
+    console.print(table)
+    console.print()
+
+
+def print_emails(emails):
+    if not emails:
+        console.print("[dim]No emails found in commit history.[/]")
+        console.print()
+        return
+
+    table = Table(title="Discovered Emails", box=box.ROUNDED, border_style="green")
+    table.add_column("#", justify="right", style="dim")
+    table.add_column("Email", style="bold green")
+
+    for i, email in enumerate(emails, 1):
+        table.add_row(str(i), email)
+
+    console.print(table)
+    console.print()
+
+
+def print_timezone(data):
+    if data.get("confidence") == "none":
+        console.print("[dim]Not enough commit data to estimate timezone.[/]")
+        console.print()
+        return
+
+    confidence = data["confidence"]
+    if confidence == "high":
+        color = "green"
+    elif confidence == "medium":
+        color = "yellow"
+    else:
+        color = "red"
+
+    console.print(
+        Panel(
+            f"[bold]{data['estimated_timezone']}[/]\n"
+            f"Confidence: [{color}]{confidence}[/] ({data['total_commits_analyzed']} commits analyzed)\n"
+            f"Peak hours (UTC): {', '.join(f'{h:02d}:00' for h in data['peak_hours_utc'])}",
+            title="[bold]Timezone Estimate[/]",
+            border_style="magenta",
+            padding=(1, 2),
+        )
+    )
+    console.print()
+
+    if data.get("hour_distribution"):
+        table = Table(title="Commit Hour Distribution (UTC)", box=box.SIMPLE)
+        table.add_column("Hour", justify="right")
+        table.add_column("Commits", justify="right")
+        table.add_column("Graph")
+
+        max_val = max(data["hour_distribution"].values()) if data["hour_distribution"] else 1
+        for hour in range(24):
+            count = data["hour_distribution"].get(hour, 0)
+            if count > 0:
+                bar_len = int(count / max_val * 25)
+                bar = "█" * bar_len
+                table.add_row(f"{hour:02d}:00", str(count), f"[cyan]{bar}[/]")
+
+        console.print(table)
+        console.print()
+
+
+def print_activity(data):
+    console.print(f"[bold]Activity Patterns[/] — {data['total_events']} events analyzed")
+    if data.get("last_activity"):
+        console.print(f"  Last activity: [green]{data['last_activity']}[/]")
+    if data.get("streak"):
+        console.print(f"  Current streak: [yellow]{data['streak']} day(s)[/]")
+    console.print()
+
+    if data["by_day"]:
+        day_table = Table(title="Activity by Day", box=box.SIMPLE)
+        day_table.add_column("Day", style="bold")
+        day_table.add_column("Count", justify="right")
+        day_table.add_column("Graph")
+
+        max_day = max(data["by_day"].values()) if any(data["by_day"].values()) else 1
+        for day, count in data["by_day"].items():
+            bar_len = int(count / max_day * 20) if max_day > 0 else 0
+            bar = "█" * bar_len
+            day_table.add_row(day[:3], str(count), f"[cyan]{bar}[/]")
+
+        console.print(day_table)
+        console.print()
+
+    if data["event_types"]:
+        type_table = Table(title="Event Types", box=box.SIMPLE)
+        type_table.add_column("Type", style="bold")
+        type_table.add_column("Count", justify="right")
+
+        for etype, count in data["event_types"].items():
+            name = etype.replace("Event", "")
+            type_table.add_row(name, str(count))
+
+        console.print(type_table)
+        console.print()
+
+
+def print_tech_stack(data):
+    console.print(
+        f"[bold]Tech Stack[/] — {data['original_repos']} original repos, "
+        f"{data['forked_repos']} forks"
+    )
+    console.print()
+
+    if data["languages"]:
+        table = Table(title="Languages", box=box.ROUNDED, border_style="magenta")
+        table.add_column("Language", style="bold")
+        table.add_column("Repos", justify="right")
+        table.add_column("Graph")
+
+        max_val = max(data["languages"].values()) if data["languages"] else 1
+        colors = ["cyan", "green", "yellow", "red", "blue", "magenta"]
+        for i, (lang, count) in enumerate(data["languages"].items()):
+            color = colors[i % len(colors)]
+            bar_len = int(count / max_val * 20)
+            bar = "█" * bar_len
+            table.add_row(lang, str(count), f"[{color}]{bar}[/]")
+
+        console.print(table)
+        console.print()
+
+    if data["topics"]:
+        topics_str = ", ".join(f"[dim]{t}[/]" for t in data["topics"])
+        console.print(f"  Topics: {topics_str}")
+        console.print()
+
+
+def print_collaborators(data):
+    if data["organizations"]:
+        console.print(f"[bold]Organizations:[/] {', '.join(data['organizations'])}")
+        console.print()
+
+    if data["frequent_collaborators"]:
+        table = Table(title="Frequent Collaborators", box=box.ROUNDED, border_style="yellow")
+        table.add_column("User", style="bold")
+        table.add_column("Interactions", justify="right")
+
+        for user, count in data["frequent_collaborators"].items():
+            table.add_row(f"@{user}", str(count))
+
+        console.print(table)
+        console.print()
+
+    if data["following"]:
+        console.print(f"[bold]Following ({data['following_count']}):[/] {', '.join(data['following'][:15])}")
+        if data["following_count"] > 15:
+            console.print(f"  [dim]... and {data['following_count'] - 15} more[/]")
+        console.print()
+
+
+def print_identities(data):
+    if not data["identities"]:
+        return
+
+    table = Table(title="Commit Identities", box=box.ROUNDED, border_style="red")
+    table.add_column("Email", style="bold")
+    table.add_column("Names Used")
+    table.add_column("Noreply?")
+
+    for identity in data["identities"]:
+        names = ", ".join(identity["names"])
+        noreply = "[dim]yes[/]" if identity["is_noreply"] else "[yellow]no[/]"
+        table.add_row(identity["email"], names, noreply)
+
+    console.print(table)
+    console.print(
+        f"  [dim]{data['unique_emails']} unique email(s), "
+        f"{data['unique_names']} unique name(s)[/]"
+    )
+    console.print()
+
+
+def print_full_scan(report):
+    print_profile(report["profile"])
+    print_emails(report["emails"])
+    print_timezone(report["timezone"])
+    print_activity(report["activity"])
+    print_tech_stack(report["tech_stack"])
+    print_collaborators(report["collaborators"])
+    print_identities(report["identities"])

ghspy-0.1.0/ghspy/github_api.py

@@ -0,0 +1,85 @@
+"""GitHub API client for GhSpy."""
+
+import os
+import sys
+
+import requests
+
+
+class GitHubClient:
+    BASE_URL = "https://api.github.com"
+
+    def __init__(self, token=None):
+        self.token = token or os.environ.get("GITHUB_TOKEN")
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Accept": "application/vnd.github.v3+json",
+            "User-Agent": "GhSpy",
+        })
+        if self.token:
+            self.session.headers["Authorization"] = f"token {self.token}"
+
+    def _get(self, endpoint, params=None):
+        url = f"{self.BASE_URL}{endpoint}"
+        resp = self.session.get(url, params=params)
+        if resp.status_code == 403 and "rate limit" in resp.text.lower():
+            print("GitHub API rate limit exceeded. Set GITHUB_TOKEN for higher limits.")
+            sys.exit(1)
+        if resp.status_code == 404:
+            print(f"Not found: {endpoint}")
+            sys.exit(1)
+        resp.raise_for_status()
+        return resp.json()
+
+    def _get_paginated(self, endpoint, params=None, max_pages=5):
+        params = params or {}
+        params.setdefault("per_page", 100)
+        results = []
+        for page in range(1, max_pages + 1):
+            params["page"] = page
+            data = self._get(endpoint, params)
+            if not data:
+                break
+            results.extend(data)
+        return results
+
+    def get_user(self, username):
+        return self._get(f"/users/{username}")
+
+    def get_repos(self, username, max_pages=3):
+        return self._get_paginated(
+            f"/users/{username}/repos",
+            params={"sort": "updated"},
+            max_pages=max_pages,
+        )
+
+    def get_events(self, username, max_pages=3):
+        return self._get_paginated(
+            f"/users/{username}/events/public",
+            max_pages=max_pages,
+        )
+
+    def get_repo_commits(self, owner, repo, author=None, max_pages=2):
+        params = {}
+        if author:
+            params["author"] = author
+        return self._get_paginated(
+            f"/repos/{owner}/{repo}/commits",
+            params=params,
+            max_pages=max_pages,
+        )
+
+    def get_orgs(self, username):
+        return self._get(f"/users/{username}/orgs")
+
+    def get_followers(self, username):
+        return self._get_paginated(f"/users/{username}/followers", max_pages=2)
+
+    def get_following(self, username):
+        return self._get_paginated(f"/users/{username}/following", max_pages=2)
+
+    def get_gists(self, username):
+        return self._get_paginated(f"/users/{username}/gists", max_pages=2)
+
+    def get_rate_limit(self):
+        return self._get("/rate_limit")

ghspy-0.1.0/ghspy.egg-info/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: ghspy
+Version: 0.1.0
+Summary: GitHub OSINT tool — extract intelligence from any GitHub user profile
+Author: shazeus
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shazeus/ghspy
+Project-URL: Repository, https://github.com/shazeus/ghspy
+Project-URL: Issues, https://github.com/shazeus/ghspy/issues
+Keywords: github,osint,reconnaissance,cli,security,intelligence
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: rich>=13.0
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">GhSpy</h1>
+  <p align="center">GitHub OSINT tool — extract intelligence from any GitHub user profile.</p>
+  <p align="center">
+    <a href="https://pypi.org/project/ghspy/"><img src="https://img.shields.io/pypi/v/ghspy?color=blue&label=PyPI" alt="PyPI"></a>
+    <a href="https://pypi.org/project/ghspy/"><img src="https://img.shields.io/pypi/pyversions/ghspy" alt="Python"></a>
+    <a href="https://github.com/shazeus/ghspy/blob/main/LICENSE"><img src="https://img.shields.io/github/license/shazeus/ghspy" alt="License"></a>
+    <a href="https://github.com/shazeus/ghspy/stargazers"><img src="https://img.shields.io/github/stars/shazeus/ghspy?style=social" alt="Stars"></a>
+  </p>
+</p>
+
+---
+
+Discover emails, estimate timezones, map tech stacks, find collaborators, and analyze activity patterns — all from your terminal. GhSpy uses the public GitHub API to gather open-source intelligence on any GitHub user.
+
+- **Email Discovery** — extract real email addresses from commit history
+- **Timezone Estimation** — estimate location from commit hour patterns
+- **Activity Analysis** — peak hours, active days, contribution streaks
+- **Tech Stack Mapping** — languages, topics, original vs forked repos
+- **Collaborator Detection** — frequent interactions, orgs, following
+- **Identity Mapping** — cross-reference commit emails and author names
+
+## Installation
+
+```bash
+pip install ghspy
+```
+
+Requires Python 3.8+. Works on Linux, macOS, and Windows.
+
+## Usage
+
+```bash
+# Full OSINT scan
+ghspy scan torvalds
+
+# Extract emails from commit history
+ghspy emails dhh
+
+# Estimate timezone
+ghspy timezone antirez
+
+# Activity patterns
+ghspy activity shazeus
+
+# Tech stack
+ghspy techstack gvanrossum
+
+# Collaborators & organizations
+ghspy collabs octocat
+
+# Export to JSON
+ghspy export torvalds --format json -o report.json
+
+# Export to CSV
+ghspy export torvalds --format csv -o report.csv
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ghspy scan <user>` | Full OSINT scan with all modules |
+| `ghspy emails <user>` | Extract emails from commit history |
+| `ghspy timezone <user>` | Estimate timezone from commit patterns |
+| `ghspy activity <user>` | Activity breakdown by hour, day, and event type |
+| `ghspy techstack <user>` | Languages, topics, and repo statistics |
+| `ghspy collabs <user>` | Collaborators, organizations, and following |
+| `ghspy export <user>` | Export findings to JSON or CSV |
+| `ghspy rate-limit` | Check GitHub API rate limit |
+
+## Configuration
+
+### GitHub Token
+
+Without a token you get **60 requests/hour**. With a token you get **5,000 requests/hour**. A full scan uses 20–50 requests depending on the user's repo count.
+
+```bash
+# Set as environment variable (recommended)
+export GITHUB_TOKEN=ghp_your_token_here
+
+# Or pass directly
+ghspy --token ghp_xxxx scan torvalds
+```
+
+Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens) — no special scopes needed for public data.
+
+### JSON Output
+
+Every command supports `--json-output` for piping to other tools:
+
+```bash
+ghspy scan user --json-output | jq '.emails'
+ghspy scan user --json-output | jq '.timezone.estimated_timezone'
+```
+
+## How It Works
+
+GhSpy queries the public GitHub REST API to collect:
+
+1. **User profile** — public info, bio, location, social links
+2. **Repositories** — languages, topics, fork status, activity dates
+3. **Commit history** — author emails, timestamps, committer info
+4. **Public events** — pushes, PRs, issues, comments
+5. **Social graph** — followers, following, organizations
+
+All data is publicly available through GitHub's API. No authentication bypass or scraping is involved.
+
+## Disclaimer
+
+This tool only accesses **publicly available data** through the official GitHub API. It does not bypass access controls, scrape private information, or violate GitHub's Terms of Service. Use responsibly.
+
+## License
+
+[MIT](LICENSE)

ghspy-0.1.0/ghspy.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+ghspy/__init__.py
+ghspy/__main__.py
+ghspy/analyzer.py
+ghspy/cli.py
+ghspy/display.py
+ghspy/github_api.py
+ghspy.egg-info/PKG-INFO
+ghspy.egg-info/SOURCES.txt
+ghspy.egg-info/dependency_links.txt
+ghspy.egg-info/entry_points.txt
+ghspy.egg-info/requires.txt
+ghspy.egg-info/top_level.txt

ghspy-0.1.0/ghspy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ghspy-0.1.0/ghspy.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ghspy = ghspy.cli:cli

ghspy-0.1.0/ghspy.egg-info/requires.txt

@@ -0,0 +1,3 @@
+click>=8.0
+requests>=2.28
+rich>=13.0

ghspy-0.1.0/ghspy.egg-info/top_level.txt

@@ -0,0 +1 @@
+ghspy

ghspy-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ghspy"
+version = "0.1.0"
+description = "GitHub OSINT tool — extract intelligence from any GitHub user profile"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [
+    {name = "shazeus"},
+]
+keywords = ["github", "osint", "reconnaissance", "cli", "security", "intelligence"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "click>=8.0",
+    "requests>=2.28",
+    "rich>=13.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/shazeus/ghspy"
+Repository = "https://github.com/shazeus/ghspy"
+Issues = "https://github.com/shazeus/ghspy/issues"
+
+[project.scripts]
+ghspy = "ghspy.cli:cli"
+
+[tool.setuptools.packages.find]
+include = ["ghspy*"]

ghspy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+