sosmed-scanner 0.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sosmed_scanner-0.4.0/LICENSE +21 -0
- sosmed_scanner-0.4.0/PKG-INFO +130 -0
- sosmed_scanner-0.4.0/README.md +110 -0
- sosmed_scanner-0.4.0/pyproject.toml +49 -0
- sosmed_scanner-0.4.0/setup.cfg +4 -0
- sosmed_scanner-0.4.0/sosmed_scanner/__init__.py +3 -0
- sosmed_scanner-0.4.0/sosmed_scanner/cli.py +124 -0
- sosmed_scanner-0.4.0/sosmed_scanner/log.py +24 -0
- sosmed_scanner-0.4.0/sosmed_scanner/network.py +46 -0
- sosmed_scanner-0.4.0/sosmed_scanner/scanner.py +141 -0
- sosmed_scanner-0.4.0/sosmed_scanner.egg-info/PKG-INFO +130 -0
- sosmed_scanner-0.4.0/sosmed_scanner.egg-info/SOURCES.txt +20 -0
- sosmed_scanner-0.4.0/sosmed_scanner.egg-info/dependency_links.txt +1 -0
- sosmed_scanner-0.4.0/sosmed_scanner.egg-info/entry_points.txt +2 -0
- sosmed_scanner-0.4.0/sosmed_scanner.egg-info/top_level.txt +1 -0
- sosmed_scanner-0.4.0/tests/test_cli.py +114 -0
- sosmed_scanner-0.4.0/tests/test_integration.py +91 -0
- sosmed_scanner-0.4.0/tests/test_network.py +57 -0
- sosmed_scanner-0.4.0/tests/test_platforms.py +71 -0
- sosmed_scanner-0.4.0/tests/test_sosmed_scanner.py +109 -0
- sosmed_scanner-0.4.0/tests/test_structured_logging.py +77 -0
- sosmed_scanner-0.4.0/tests/test_version.py +18 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Nuzuli
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sosmed-scanner
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Check whether a username exists on public profile pages - 20 platforms, zero dependencies (Python standard library only).
|
|
5
|
+
Author: Nuzuli
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Nuzuli/sosmed-scanner
|
|
8
|
+
Project-URL: Repository, https://github.com/Nuzuli/sosmed-scanner
|
|
9
|
+
Keywords: username-checker,osint,cli,social-media
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Internet
|
|
16
|
+
Requires-Python: >=3.8
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
Dynamic: license-file
|
|
20
|
+
|
|
21
|
+
# Sosmed Scanner
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+

|
|
26
|
+
|
|
27
|
+

|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
A small Python command-line tool that checks whether a username exists on public profile pages. It uses only the standard library and reads public information only.
|
|
32
|
+
|
|
33
|
+
## Project Type
|
|
34
|
+
|
|
35
|
+
This is a standard library only command-line tool, not infrastructure code.
|
|
36
|
+
|
|
37
|
+
## Features
|
|
38
|
+
|
|
39
|
+
- Checks 20 platforms: GitHub, GitLab, Reddit, Medium, DEV, PyPI, YouTube, Mastodon, Tumblr, Flickr, SoundCloud, Dribbble, Linktree, Gravatar, Codeberg, SourceHut, Keybase, Chess.com, Docker Hub, and Hugging Face.
|
|
40
|
+
- Three clear statuses: `found`, `not_found`, and `unknown` (for blocked or failed requests).
|
|
41
|
+
- Plain text, JSON, or CSV output.
|
|
42
|
+
- Polite by default: sends a descriptive User-Agent, uses a timeout, and waits between requests.
|
|
43
|
+
- Optional debug logging with `--verbose`.
|
|
44
|
+
- No third-party runtime dependencies.
|
|
45
|
+
|
|
46
|
+
## Architecture
|
|
47
|
+
|
|
48
|
+
- `sosmed_scanner/network.py`: HTTP request helper. Network errors are returned as data, never raised.
|
|
49
|
+
- `sosmed_scanner/scanner.py`: platform list, username validation, and the scan loop.
|
|
50
|
+
- `sosmed_scanner/cli.py`: argument parsing, logging setup, and output formatting.
|
|
51
|
+
- `tests/`: unit and integration tests that use mocks, so no real network access is needed.
|
|
52
|
+
|
|
53
|
+
### Quick Start (fresh clone)
|
|
54
|
+
|
|
55
|
+
The tool itself runs on Python 3.8 or newer and has no dependencies. The development toolchain (tests, lint, type checks) is pinned for Python 3.12, which is what CI uses.
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
git clone https://github.com/Nuzuli/sosmed-scanner.git
|
|
59
|
+
cd sosmed-scanner
|
|
60
|
+
python -m venv .venv
|
|
61
|
+
source .venv/bin/activate
|
|
62
|
+
pip install -r requirements-dev.lock
|
|
63
|
+
pytest
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
On Windows, activate the environment with `.venv\Scripts\activate`.
|
|
67
|
+
|
|
68
|
+
`requirements-dev.lock` is committed to the repository and checked by CI, so every install uses the same pinned versions. After changing `requirements-dev.txt`, regenerate the lockfile by running the "Update lockfile" workflow in the Actions tab; CI fails if the two files disagree.
|
|
69
|
+
|
|
70
|
+
## Usage
|
|
71
|
+
|
|
72
|
+
Run from the repository root:
|
|
73
|
+
|
|
74
|
+
`python -m sosmed_scanner.cli target_username`
|
|
75
|
+
|
|
76
|
+
Options:
|
|
77
|
+
|
|
78
|
+
- `-p`, `--platform NAME`: scan only this platform (repeatable), for example `-p github -p dev`
|
|
79
|
+
- `--json`: print results as JSON
|
|
80
|
+
- `--csv`: print results as CSV (columns: platform, status, url, detail)
|
|
81
|
+
- `--delay SECONDS`: pause between requests (default `0.5`)
|
|
82
|
+
- `-v`, `--verbose`: print debug details to stderr
|
|
83
|
+
|
|
84
|
+
Example output:
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
GitHub found https://github.com/alice
|
|
88
|
+
GitLab not_found https://gitlab.com/alice
|
|
89
|
+
Reddit unknown https://www.reddit.com/user/alice (HTTP 429)
|
|
90
|
+
```
|
|
91
|
+
## Logging
|
|
92
|
+
|
|
93
|
+
Diagnostic messages are emitted at DEBUG level as one JSON object per record. Every record has an `event` key plus event-specific fields, for example:
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{"event": "fetch_done", "status": 200, "url": "https://github.com/octocat"}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Events: `scan_start`, `platform_result`, `scan_done`, `fetch_start`, `fetch_done`, `fetch_failed`.
|
|
100
|
+
|
|
101
|
+
## Exit Codes
|
|
102
|
+
|
|
103
|
+
- `0`: scan finished
|
|
104
|
+
- `2`: invalid input (bad username or unknown platform)
|
|
105
|
+
|
|
106
|
+
## Understanding Results
|
|
107
|
+
|
|
108
|
+
- `found`: the profile page returned HTTP 200.
|
|
109
|
+
- `not_found`: the profile page returned HTTP 404.
|
|
110
|
+
- `unknown`: anything else, such as rate limiting, blocking, or a network error. The `detail` field explains why.
|
|
111
|
+
|
|
112
|
+
## Development
|
|
113
|
+
|
|
114
|
+
Run the checks locally:
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
ruff check sosmed_scanner tests
|
|
118
|
+
mypy sosmed_scanner
|
|
119
|
+
pytest -v --cov=sosmed_scanner --cov-fail-under=80
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The same checks, plus a dependency audit, run on every push through GitHub Actions.
|
|
123
|
+
|
|
124
|
+
## Responsible Use
|
|
125
|
+
|
|
126
|
+
Use this tool only for lawful purposes, such as checking your own username or brand. It reads public pages only. Respect each platform's terms of service and do not use it for harassment or profiling people.
|
|
127
|
+
|
|
128
|
+
## License
|
|
129
|
+
|
|
130
|
+
MIT License. See `LICENSE`.
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Sosmed Scanner
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
A small Python command-line tool that checks whether a username exists on public profile pages. It uses only the standard library and reads public information only.
|
|
12
|
+
|
|
13
|
+
## Project Type
|
|
14
|
+
|
|
15
|
+
This is a standard library only command-line tool, not infrastructure code.
|
|
16
|
+
|
|
17
|
+
## Features
|
|
18
|
+
|
|
19
|
+
- Checks 20 platforms: GitHub, GitLab, Reddit, Medium, DEV, PyPI, YouTube, Mastodon, Tumblr, Flickr, SoundCloud, Dribbble, Linktree, Gravatar, Codeberg, SourceHut, Keybase, Chess.com, Docker Hub, and Hugging Face.
|
|
20
|
+
- Three clear statuses: `found`, `not_found`, and `unknown` (for blocked or failed requests).
|
|
21
|
+
- Plain text, JSON, or CSV output.
|
|
22
|
+
- Polite by default: sends a descriptive User-Agent, uses a timeout, and waits between requests.
|
|
23
|
+
- Optional debug logging with `--verbose`.
|
|
24
|
+
- No third-party runtime dependencies.
|
|
25
|
+
|
|
26
|
+
## Architecture
|
|
27
|
+
|
|
28
|
+
- `sosmed_scanner/network.py`: HTTP request helper. Network errors are returned as data, never raised.
|
|
29
|
+
- `sosmed_scanner/scanner.py`: platform list, username validation, and the scan loop.
|
|
30
|
+
- `sosmed_scanner/cli.py`: argument parsing, logging setup, and output formatting.
|
|
31
|
+
- `tests/`: unit and integration tests that use mocks, so no real network access is needed.
|
|
32
|
+
|
|
33
|
+
### Quick Start (fresh clone)
|
|
34
|
+
|
|
35
|
+
The tool itself runs on Python 3.8 or newer and has no dependencies. The development toolchain (tests, lint, type checks) is pinned for Python 3.12, which is what CI uses.
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
git clone https://github.com/Nuzuli/sosmed-scanner.git
|
|
39
|
+
cd sosmed-scanner
|
|
40
|
+
python -m venv .venv
|
|
41
|
+
source .venv/bin/activate
|
|
42
|
+
pip install -r requirements-dev.lock
|
|
43
|
+
pytest
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
On Windows, activate the environment with `.venv\Scripts\activate`.
|
|
47
|
+
|
|
48
|
+
`requirements-dev.lock` is committed to the repository and checked by CI, so every install uses the same pinned versions. After changing `requirements-dev.txt`, regenerate the lockfile by running the "Update lockfile" workflow in the Actions tab; CI fails if the two files disagree.
|
|
49
|
+
|
|
50
|
+
## Usage
|
|
51
|
+
|
|
52
|
+
Run from the repository root:
|
|
53
|
+
|
|
54
|
+
`python -m sosmed_scanner.cli target_username`
|
|
55
|
+
|
|
56
|
+
Options:
|
|
57
|
+
|
|
58
|
+
- `-p`, `--platform NAME`: scan only this platform (repeatable), for example `-p github -p dev`
|
|
59
|
+
- `--json`: print results as JSON
|
|
60
|
+
- `--csv`: print results as CSV (columns: platform, status, url, detail)
|
|
61
|
+
- `--delay SECONDS`: pause between requests (default `0.5`)
|
|
62
|
+
- `-v`, `--verbose`: print debug details to stderr
|
|
63
|
+
|
|
64
|
+
Example output:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
GitHub found https://github.com/alice
|
|
68
|
+
GitLab not_found https://gitlab.com/alice
|
|
69
|
+
Reddit unknown https://www.reddit.com/user/alice (HTTP 429)
|
|
70
|
+
```
|
|
71
|
+
## Logging
|
|
72
|
+
|
|
73
|
+
Diagnostic messages are emitted at DEBUG level as one JSON object per record. Every record has an `event` key plus event-specific fields, for example:
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
{"event": "fetch_done", "status": 200, "url": "https://github.com/octocat"}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Events: `scan_start`, `platform_result`, `scan_done`, `fetch_start`, `fetch_done`, `fetch_failed`.
|
|
80
|
+
|
|
81
|
+
## Exit Codes
|
|
82
|
+
|
|
83
|
+
- `0`: scan finished
|
|
84
|
+
- `2`: invalid input (bad username or unknown platform)
|
|
85
|
+
|
|
86
|
+
## Understanding Results
|
|
87
|
+
|
|
88
|
+
- `found`: the profile page returned HTTP 200.
|
|
89
|
+
- `not_found`: the profile page returned HTTP 404.
|
|
90
|
+
- `unknown`: anything else, such as rate limiting, blocking, or a network error. The `detail` field explains why.
|
|
91
|
+
|
|
92
|
+
## Development
|
|
93
|
+
|
|
94
|
+
Run the checks locally:
|
|
95
|
+
|
|
96
|
+
```
|
|
97
|
+
ruff check sosmed_scanner tests
|
|
98
|
+
mypy sosmed_scanner
|
|
99
|
+
pytest -v --cov=sosmed_scanner --cov-fail-under=80
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The same checks, plus a dependency audit, run on every push through GitHub Actions.
|
|
103
|
+
|
|
104
|
+
## Responsible Use
|
|
105
|
+
|
|
106
|
+
Use this tool only for lawful purposes, such as checking your own username or brand. It reads public pages only. Respect each platform's terms of service and do not use it for harassment or profiling people.
|
|
107
|
+
|
|
108
|
+
## License
|
|
109
|
+
|
|
110
|
+
MIT License. See `LICENSE`.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "sosmed-scanner"
|
|
7
|
+
version = "0.4.0"
|
|
8
|
+
description = "Check whether a username exists on public profile pages - 20 platforms, zero dependencies (Python standard library only)."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.8"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "Nuzuli" },
|
|
14
|
+
]
|
|
15
|
+
keywords = ["username-checker", "osint", "cli", "social-media"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 3 - Alpha",
|
|
18
|
+
"Environment :: Console",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"License :: OSI Approved :: MIT License",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Topic :: Internet",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
[project.urls]
|
|
26
|
+
Homepage = "https://github.com/Nuzuli/sosmed-scanner"
|
|
27
|
+
Repository = "https://github.com/Nuzuli/sosmed-scanner"
|
|
28
|
+
|
|
29
|
+
[project.scripts]
|
|
30
|
+
sosmed-scanner = "sosmed_scanner.cli:main"
|
|
31
|
+
|
|
32
|
+
[tool.setuptools]
|
|
33
|
+
packages = ["sosmed_scanner"]
|
|
34
|
+
|
|
35
|
+
[tool.ruff]
|
|
36
|
+
line-length = 100
|
|
37
|
+
|
|
38
|
+
[tool.ruff.lint]
|
|
39
|
+
select = ["E", "F", "W"]
|
|
40
|
+
ignore = ["W292"]
|
|
41
|
+
|
|
42
|
+
[tool.mypy]
|
|
43
|
+
python_version = "3.12"
|
|
44
|
+
warn_return_any = true
|
|
45
|
+
warn_unused_ignores = true
|
|
46
|
+
|
|
47
|
+
[tool.pytest.ini_options]
|
|
48
|
+
testpaths = ["tests"]
|
|
49
|
+
pythonpath = ["."]
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
"""Command-line interface for Sosmed Scanner."""
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
import csv
|
|
5
|
+
import io
|
|
6
|
+
import json
|
|
7
|
+
import logging
|
|
8
|
+
import sys
|
|
9
|
+
from dataclasses import asdict
|
|
10
|
+
from typing import List, Optional, Sequence
|
|
11
|
+
|
|
12
|
+
from sosmed_scanner.scanner import PLATFORMS, ScanResult, scan_username
|
|
13
|
+
|
|
14
|
+
# Fixed name: __name__ is "__main__" when run with `python -m`.
|
|
15
|
+
logger = logging.getLogger("sosmed_scanner.cli")
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def configure_logging(verbose: bool) -> None:
|
|
19
|
+
"""Send log messages to stderr; show debug details when verbose."""
|
|
20
|
+
package_logger = logging.getLogger("sosmed_scanner")
|
|
21
|
+
package_logger.handlers.clear()
|
|
22
|
+
handler = logging.StreamHandler(sys.stderr)
|
|
23
|
+
handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
|
|
24
|
+
package_logger.addHandler(handler)
|
|
25
|
+
package_logger.setLevel(logging.DEBUG if verbose else logging.WARNING)
|
|
26
|
+
package_logger.propagate = False
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
30
|
+
parser = argparse.ArgumentParser(
|
|
31
|
+
prog="sosmed_scanner",
|
|
32
|
+
description="Check whether a username exists on public profile pages.",
|
|
33
|
+
)
|
|
34
|
+
parser.add_argument("username", help="Username to look up")
|
|
35
|
+
parser.add_argument(
|
|
36
|
+
"-p",
|
|
37
|
+
"--platform",
|
|
38
|
+
action="append",
|
|
39
|
+
help="Limit the scan to a platform (repeatable). Available: "
|
|
40
|
+
+ ", ".join(PLATFORMS),
|
|
41
|
+
)
|
|
42
|
+
parser.add_argument(
|
|
43
|
+
"--json", action="store_true", help="Print results as JSON"
|
|
44
|
+
)
|
|
45
|
+
parser.add_argument(
|
|
46
|
+
"--csv", action="store_true", help="Print results as CSV"
|
|
47
|
+
)
|
|
48
|
+
parser.add_argument(
|
|
49
|
+
"--delay",
|
|
50
|
+
type=float,
|
|
51
|
+
default=0.5,
|
|
52
|
+
help="Seconds to wait between requests (default: 0.5)",
|
|
53
|
+
)
|
|
54
|
+
parser.add_argument(
|
|
55
|
+
"-v",
|
|
56
|
+
"--verbose",
|
|
57
|
+
action="store_true",
|
|
58
|
+
help="Show debug details on stderr",
|
|
59
|
+
)
|
|
60
|
+
return parser
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def validate_platforms(names: Optional[Sequence[str]]) -> None:
|
|
64
|
+
"""Raise ValueError naming the unknown platforms and the valid choices.
|
|
65
|
+
|
|
66
|
+
Names are matched case-insensitively, like the scanner itself does.
|
|
67
|
+
"""
|
|
68
|
+
if not names:
|
|
69
|
+
return
|
|
70
|
+
known = {name.lower() for name in PLATFORMS}
|
|
71
|
+
unknown = [name for name in names if name.lower() not in known]
|
|
72
|
+
if unknown:
|
|
73
|
+
raise ValueError(
|
|
74
|
+
f"Unknown platform: {', '.join(unknown)}. "
|
|
75
|
+
f"Available: {', '.join(PLATFORMS)}"
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def format_results(results: List[ScanResult]) -> str:
|
|
80
|
+
"""Render results as aligned plain text."""
|
|
81
|
+
lines = []
|
|
82
|
+
for item in results:
|
|
83
|
+
line = f"{item.platform:<12} {item.status:<10} {item.url}"
|
|
84
|
+
if item.detail:
|
|
85
|
+
line += f" ({item.detail})"
|
|
86
|
+
lines.append(line)
|
|
87
|
+
return "\n".join(lines)
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def format_csv(results: List[ScanResult]) -> str:
|
|
91
|
+
"""Render results as CSV with a header row."""
|
|
92
|
+
buffer = io.StringIO()
|
|
93
|
+
writer = csv.writer(buffer)
|
|
94
|
+
writer.writerow(["platform", "status", "url", "detail"])
|
|
95
|
+
for item in results:
|
|
96
|
+
writer.writerow(
|
|
97
|
+
[item.platform, item.status, item.url, item.detail or ""]
|
|
98
|
+
)
|
|
99
|
+
return buffer.getvalue().rstrip("\r\n")
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def main(argv: Optional[Sequence[str]] = None) -> int:
|
|
103
|
+
"""Run the CLI and return an exit code (0 ok, 2 invalid input)."""
|
|
104
|
+
args = build_parser().parse_args(argv)
|
|
105
|
+
configure_logging(args.verbose)
|
|
106
|
+
try:
|
|
107
|
+
validate_platforms(args.platform)
|
|
108
|
+
results = scan_username(
|
|
109
|
+
args.username, platforms=args.platform, delay=args.delay
|
|
110
|
+
)
|
|
111
|
+
except ValueError as error:
|
|
112
|
+
logger.error("%s", error)
|
|
113
|
+
return 2
|
|
114
|
+
if args.json:
|
|
115
|
+
print(json.dumps([asdict(item) for item in results], indent=2))
|
|
116
|
+
elif args.csv:
|
|
117
|
+
print(format_csv(results))
|
|
118
|
+
else:
|
|
119
|
+
print(format_results(results))
|
|
120
|
+
return 0
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
if __name__ == "__main__":
|
|
124
|
+
sys.exit(main())
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""Structured (JSON) logging helper."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import json
|
|
5
|
+
import logging
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def log_event(
|
|
10
|
+
logger: logging.Logger,
|
|
11
|
+
event: str,
|
|
12
|
+
*,
|
|
13
|
+
level: int = logging.DEBUG,
|
|
14
|
+
**fields: Any,
|
|
15
|
+
) -> None:
|
|
16
|
+
"""Emit one log record whose message is a JSON object.
|
|
17
|
+
|
|
18
|
+
The payload always has an "event" key; extra keyword arguments
|
|
19
|
+
become additional keys. Non-serializable values fall back to str().
|
|
20
|
+
"""
|
|
21
|
+
if not logger.isEnabledFor(level):
|
|
22
|
+
return
|
|
23
|
+
payload = {"event": event, **fields}
|
|
24
|
+
logger.log(level, json.dumps(payload, default=str, sort_keys=True))
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
"""Low-level HTTP helpers built on the standard library only."""
|
|
2
|
+
|
|
3
|
+
import logging
|
|
4
|
+
import urllib.error
|
|
5
|
+
import urllib.request
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
from typing import Optional
|
|
8
|
+
|
|
9
|
+
from sosmed_scanner import __version__
|
|
10
|
+
from sosmed_scanner.log import log_event
|
|
11
|
+
|
|
12
|
+
USER_AGENT = (
|
|
13
|
+
f"sosmed-scanner/{__version__} (+https://github.com/Nuzuli/sosmed-scanner)"
|
|
14
|
+
)
|
|
15
|
+
DEFAULT_TIMEOUT = 8.0
|
|
16
|
+
|
|
17
|
+
logger = logging.getLogger(__name__)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@dataclass(frozen=True)
|
|
21
|
+
class HttpResult:
|
|
22
|
+
"""Outcome of a single HTTP request."""
|
|
23
|
+
|
|
24
|
+
url: str
|
|
25
|
+
status: Optional[int]
|
|
26
|
+
error: Optional[str] = None
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def fetch_status(url: str, timeout: float = DEFAULT_TIMEOUT) -> HttpResult:
|
|
30
|
+
"""Request a public URL and return its HTTP status code.
|
|
31
|
+
|
|
32
|
+
Network problems never raise: they are reported through ``error``.
|
|
33
|
+
"""
|
|
34
|
+
log_event(logger, "fetch_start", url=url, timeout=timeout)
|
|
35
|
+
request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
|
|
36
|
+
try:
|
|
37
|
+
with urllib.request.urlopen(request, timeout=timeout) as response:
|
|
38
|
+
log_event(logger, "fetch_done", url=url, status=response.status)
|
|
39
|
+
return HttpResult(url=url, status=response.status)
|
|
40
|
+
except urllib.error.HTTPError as error:
|
|
41
|
+
log_event(logger, "fetch_done", url=url, status=error.code)
|
|
42
|
+
return HttpResult(url=url, status=error.code)
|
|
43
|
+
except OSError as error:
|
|
44
|
+
# URLError and TimeoutError are both subclasses of OSError.
|
|
45
|
+
log_event(logger, "fetch_failed", url=url, error=error)
|
|
46
|
+
return HttpResult(url=url, status=None, error=str(error))
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
"""Scan public profile pages for a username."""
|
|
2
|
+
|
|
3
|
+
import logging
|
|
4
|
+
import re
|
|
5
|
+
import time
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
from typing import Callable, Dict, List, Optional, Sequence
|
|
8
|
+
|
|
9
|
+
from sosmed_scanner.log import log_event
|
|
10
|
+
from sosmed_scanner.network import HttpResult, fetch_status
|
|
11
|
+
|
|
12
|
+
logger = logging.getLogger(__name__)
|
|
13
|
+
|
|
14
|
+
PLATFORMS: Dict[str, str] = {
|
|
15
|
+
"GitHub": "https://github.com/{username}",
|
|
16
|
+
"GitLab": "https://gitlab.com/{username}",
|
|
17
|
+
"Reddit": "https://www.reddit.com/user/{username}",
|
|
18
|
+
"Medium": "https://medium.com/@{username}",
|
|
19
|
+
"DEV": "https://dev.to/{username}",
|
|
20
|
+
"PyPI": "https://pypi.org/user/{username}/",
|
|
21
|
+
"YouTube": "https://www.youtube.com/@{username}",
|
|
22
|
+
"Mastodon": "https://mastodon.social/@{username}",
|
|
23
|
+
"Tumblr": "https://{username}.tumblr.com",
|
|
24
|
+
"Flickr": "https://www.flickr.com/photos/{username}",
|
|
25
|
+
"SoundCloud": "https://soundcloud.com/{username}",
|
|
26
|
+
"Dribbble": "https://dribbble.com/{username}",
|
|
27
|
+
"Linktree": "https://linktr.ee/{username}",
|
|
28
|
+
"Gravatar": "https://gravatar.com/{username}",
|
|
29
|
+
"Codeberg": "https://codeberg.org/{username}",
|
|
30
|
+
"SourceHut": "https://sr.ht/~{username}",
|
|
31
|
+
"Keybase": "https://keybase.io/{username}",
|
|
32
|
+
"Chess.com": "https://www.chess.com/member/{username}",
|
|
33
|
+
"Docker Hub": "https://hub.docker.com/u/{username}",
|
|
34
|
+
"Hugging Face": "https://huggingface.co/{username}",
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
USERNAME_PATTERN = re.compile(r"^[A-Za-z0-9._-]{1,39}$")
|
|
38
|
+
|
|
39
|
+
FOUND = "found"
|
|
40
|
+
NOT_FOUND = "not_found"
|
|
41
|
+
UNKNOWN = "unknown"
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class InvalidUsernameError(ValueError):
|
|
45
|
+
"""Raised when a username contains unsupported characters."""
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclass(frozen=True)
|
|
49
|
+
class ScanResult:
|
|
50
|
+
"""Result of checking one platform."""
|
|
51
|
+
|
|
52
|
+
platform: str
|
|
53
|
+
url: str
|
|
54
|
+
status: str
|
|
55
|
+
detail: Optional[str] = None
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def validate_username(username: str) -> str:
|
|
59
|
+
"""Return the cleaned username or raise InvalidUsernameError."""
|
|
60
|
+
cleaned = username.strip()
|
|
61
|
+
if not USERNAME_PATTERN.match(cleaned):
|
|
62
|
+
raise InvalidUsernameError(
|
|
63
|
+
"Username must be 1-39 characters: letters, digits, '.', '_' or '-'."
|
|
64
|
+
)
|
|
65
|
+
return cleaned
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def classify(result: HttpResult) -> str:
|
|
69
|
+
"""Map an HTTP result to found, not_found, or unknown."""
|
|
70
|
+
if result.status == 200:
|
|
71
|
+
return FOUND
|
|
72
|
+
if result.status == 404:
|
|
73
|
+
return NOT_FOUND
|
|
74
|
+
return UNKNOWN
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def select_platforms(names: Optional[Sequence[str]]) -> Dict[str, str]:
|
|
78
|
+
"""Return the platforms to scan, matching names case-insensitively."""
|
|
79
|
+
if not names:
|
|
80
|
+
return dict(PLATFORMS)
|
|
81
|
+
lookup = {name.lower(): name for name in PLATFORMS}
|
|
82
|
+
selected: Dict[str, str] = {}
|
|
83
|
+
for name in names:
|
|
84
|
+
key = lookup.get(name.lower())
|
|
85
|
+
if key is None:
|
|
86
|
+
raise ValueError(f"Unknown platform: {name}")
|
|
87
|
+
selected[key] = PLATFORMS[key]
|
|
88
|
+
return selected
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def scan_username(
|
|
92
|
+
username: str,
|
|
93
|
+
platforms: Optional[Sequence[str]] = None,
|
|
94
|
+
fetch: Callable[[str], HttpResult] = fetch_status,
|
|
95
|
+
delay: float = 0.0,
|
|
96
|
+
sleep: Callable[[float], None] = time.sleep,
|
|
97
|
+
) -> List[ScanResult]:
|
|
98
|
+
"""Check a username on each selected platform, one request at a time."""
|
|
99
|
+
cleaned = validate_username(username)
|
|
100
|
+
targets = select_platforms(platforms)
|
|
101
|
+
results: List[ScanResult] = []
|
|
102
|
+
log_event(
|
|
103
|
+
logger,
|
|
104
|
+
"scan_start",
|
|
105
|
+
username=cleaned,
|
|
106
|
+
platforms=len(targets),
|
|
107
|
+
delay=delay,
|
|
108
|
+
)
|
|
109
|
+
for index, (name, template) in enumerate(targets.items()):
|
|
110
|
+
if index > 0 and delay > 0:
|
|
111
|
+
sleep(delay)
|
|
112
|
+
url = template.format(username=cleaned)
|
|
113
|
+
outcome = fetch(url)
|
|
114
|
+
detail = outcome.error
|
|
115
|
+
if detail is None and outcome.status not in (200, 404):
|
|
116
|
+
detail = f"HTTP {outcome.status}"
|
|
117
|
+
status = classify(outcome)
|
|
118
|
+
log_event(
|
|
119
|
+
logger,
|
|
120
|
+
"platform_result",
|
|
121
|
+
platform=name,
|
|
122
|
+
status=status,
|
|
123
|
+
url=url,
|
|
124
|
+
)
|
|
125
|
+
results.append(
|
|
126
|
+
ScanResult(
|
|
127
|
+
platform=name,
|
|
128
|
+
url=url,
|
|
129
|
+
status=status,
|
|
130
|
+
detail=detail,
|
|
131
|
+
)
|
|
132
|
+
)
|
|
133
|
+
found = sum(1 for item in results if item.status == FOUND)
|
|
134
|
+
log_event(
|
|
135
|
+
logger,
|
|
136
|
+
"scan_done",
|
|
137
|
+
username=cleaned,
|
|
138
|
+
checked=len(results),
|
|
139
|
+
found=found,
|
|
140
|
+
)
|
|
141
|
+
return results
|