basicbuster 0.1.0__py3-none-any.whl

basicbuster/__init__.py

@@ -0,0 +1,3 @@
+"""HTTP Basic Authentication testing CLI."""
+
+__version__ = "0.1.0"

basicbuster/cli.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from basicbuster import __version__
+from basicbuster.core import DEFAULT_TIMEOUT, run_attack
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="basicbuster",
+        description="HTTP Basic Authentication wordlist testing (authorized use only).",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    p.add_argument("--url", required=True, help="Target URL protected by HTTP Basic Auth.")
+    p.add_argument(
+        "--username",
+        metavar="FILE",
+        help="Path to username wordlist (one per line).",
+    )
+    p.add_argument(
+        "--password",
+        metavar="FILE",
+        help="Path to password wordlist (one per line).",
+    )
+    p.add_argument(
+        "--userpass",
+        metavar="FILE",
+        help="Combined file: user:pass per line.",
+    )
+    p.add_argument(
+        "--mode",
+        choices=("pitchfork", "clusterbomb"),
+        default="clusterbomb",
+        help="pitchfork: zip usernames with passwords; clusterbomb: all pairs (default).",
+    )
+    p.add_argument(
+        "--timeout",
+        type=float,
+        default=DEFAULT_TIMEOUT,
+        help=f"Per-request timeout in seconds (default: {DEFAULT_TIMEOUT}).",
+    )
+    p.add_argument(
+        "--proxy",
+        metavar="URL",
+        help="HTTP(S) proxy for all requests (e.g. http://127.0.0.1:8080).",
+    )
+    p.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Less verbose output (no probe line, no summary).",
+    )
+    return p
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        code = run_attack(args)
+    except KeyboardInterrupt:
+        print("\n[!] Interrupted.", file=sys.stderr)
+        code = 130
+    sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()

basicbuster/core.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import itertools
+from argparse import Namespace
+from pathlib import Path
+from typing import Iterable
+
+import requests
+from requests import Response
+from requests.auth import HTTPBasicAuth
+
+
+DEFAULT_TIMEOUT = 15.0
+
+
+def _proxy_dict(proxy: str | None) -> dict[str, str] | None:
+    if not proxy:
+        return None
+    return {"http": proxy, "https": proxy}
+
+
+def _read_lines(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    return [line.strip() for line in text.splitlines() if line.strip()]
+
+
+def check_basic_auth(
+    url: str,
+    timeout: float = DEFAULT_TIMEOUT,
+    proxies: dict[str, str] | None = None,
+) -> bool:
+    try:
+        r = requests.get(
+            url,
+            timeout=timeout,
+            allow_redirects=False,
+            proxies=proxies,
+        )
+    except requests.RequestException:
+        return False
+    if r.status_code != 401:
+        return False
+    www_auth = r.headers.get("WWW-Authenticate") or ""
+    return "basic" in www_auth.lower()
+
+
+def try_login(
+    url: str,
+    username: str,
+    password: str,
+    timeout: float = DEFAULT_TIMEOUT,
+    proxies: dict[str, str] | None = None,
+) -> requests.Response:
+    return requests.get(
+        url,
+        auth=HTTPBasicAuth(username, password),
+        timeout=timeout,
+        allow_redirects=False,
+        proxies=proxies,
+    )
+
+
+def pitchfork(
+    url: str,
+    usernames: Iterable[str],
+    passwords: Iterable[str],
+    timeout: float = DEFAULT_TIMEOUT,
+    proxies: dict[str, str] | None = None,
+) -> list[tuple[str, str, Response | None, str | None]]:
+    u = list(usernames)
+    p = list(passwords)
+    if not u or not p:
+        return []
+    n = min(len(u), len(p))
+    results: list[tuple[str, str, Response | None, str | None]] = []
+    for i in range(n):
+        try:
+            resp = try_login(url, u[i], p[i], timeout=timeout, proxies=proxies)
+            results.append((u[i], p[i], resp, None))
+        except requests.RequestException as e:
+            results.append((u[i], p[i], None, str(e)))
+    return results
+
+
+def clusterbomb(
+    url: str,
+    usernames: Iterable[str],
+    passwords: Iterable[str],
+    timeout: float = DEFAULT_TIMEOUT,
+    proxies: dict[str, str] | None = None,
+) -> list[tuple[str, str, Response | None, str | None]]:
+    results: list[tuple[str, str, Response | None, str | None]] = []
+    for user, pw in itertools.product(usernames, passwords):
+        try:
+            resp = try_login(url, user, pw, timeout=timeout, proxies=proxies)
+            results.append((user, pw, resp, None))
+        except requests.RequestException as e:
+            results.append((user, pw, None, str(e)))
+    return results
+
+
+def userpass_mode(
+    url: str,
+    combos: Iterable[tuple[str, str]],
+    mode: str,
+    timeout: float = DEFAULT_TIMEOUT,
+    proxies: dict[str, str] | None = None,
+) -> list[tuple[str, str, Response | None, str | None]]:
+    pairs = list(combos)
+    if not pairs:
+        return []
+    if mode == "pitchfork":
+        users = [u for u, _ in pairs]
+        pws = [p for _, p in pairs]
+        return pitchfork(url, users, pws, timeout=timeout, proxies=proxies)
+    users = [u for u, _ in pairs]
+    pws = [p for _, p in pairs]
+    return clusterbomb(url, users, pws, timeout=timeout, proxies=proxies)
+
+
+def _emit_success(user: str, pw: str, status: int) -> None:
+    print(f"[+] SUCCESS {user}:{pw} (HTTP {status})")
+
+
+def _emit_probe(ok: bool, url: str) -> None:
+    if ok:
+        print(f"[*] Target appears to use HTTP Basic Auth: {url}")
+    else:
+        print(f"[!] Target may not require HTTP Basic Auth (or unreachable): {url}")
+
+
+def run_attack(args: Namespace) -> int:
+    url = args.url
+    timeout = float(args.timeout)
+    verbose = not args.quiet
+    proxies = _proxy_dict(args.proxy)
+
+    uses_basic = check_basic_auth(url, timeout=timeout, proxies=proxies)
+    if verbose:
+        _emit_probe(uses_basic, url)
+
+    results: list[tuple[str, str, Response | None, str | None]]
+
+    if args.userpass:
+        path = Path(args.userpass)
+        if not path.is_file():
+            print(f"[!] File not found: {path}")
+            return 2
+        lines = _read_lines(path)
+        combos: list[tuple[str, str]] = []
+        for line in lines:
+            if ":" not in line:
+                print(f"[!] Invalid line (expected user:pass): {line!r}")
+                return 2
+            user, _, rest = line.partition(":")
+            combos.append((user, rest))
+        results = userpass_mode(
+            url, combos, args.mode, timeout=timeout, proxies=proxies
+        )
+    else:
+        if not args.username or not args.password:
+            print("[!] Provide --userpass or both --username and --password files.")
+            return 2
+        up = Path(args.username)
+        pp = Path(args.password)
+        if not up.is_file() or not pp.is_file():
+            print("[!] Username or password file not found.")
+            return 2
+        users = _read_lines(up)
+        pws = _read_lines(pp)
+        if args.mode == "pitchfork":
+            results = pitchfork(url, users, pws, timeout=timeout, proxies=proxies)
+        else:
+            results = clusterbomb(
+                url, users, pws, timeout=timeout, proxies=proxies
+            )
+
+    found = False
+    for user, pw, resp, err in results:
+        if resp is None:
+            if verbose and err:
+                print(f"[-] request failed for {user}:{pw} — {err}")
+            continue
+        if resp.status_code == 200:
+            _emit_success(user, pw, resp.status_code)
+            found = True
+
+    if not found and verbose:
+        print("[*] No credentials returned HTTP 200.")
+
+    return 0 if found else 1

basicbuster-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: basicbuster
+Version: 0.1.0
+Summary: CLI tool for HTTP Basic Authentication testing with wordlists.
+Author: dhina016
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dhina016/basicbuster
+Project-URL: Repository, https://github.com/dhina016/basicbuster
+Project-URL: Issues, https://github.com/dhina016/basicbuster/issues
+Keywords: security,http,basic-auth,pentest,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# basicbuster
+
+**basicbuster** is a command-line tool for testing HTTP Basic Authentication with username and password wordlists. It can detect Basic Auth on a target URL, run pitchfork or clusterbomb-style attempts, and report credentials that return HTTP `200`.
+
+## Disclaimer
+
+Use **only** on systems and applications you are **explicitly authorized** to test. Unauthorized access to computer systems is illegal. The authors are not responsible for misuse.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+After the package is [published on PyPI](https://pypi.org/project/basicbuster/), install from any machine:
+
+```bash
+pip install basicbuster
+```
+
+From a git checkout (repository root):
+
+```bash
+pip install .
+```
+
+Editable install while developing:
+
+```bash
+pip install -e .
+```
+
+### Publishing to PyPI (maintainers)
+
+The name **basicbuster** is available on PyPI. Two common options:
+
+**A — GitHub Release (recommended)**  
+After you [enable trusted publishing](https://docs.pypi.org/trusted-publishers/) for this repo on PyPI:
+
+1. In PyPI: your account → **Publishing** → add a pending publisher for `dhina016/basicbuster`, workflow file `publish.yml`.
+2. On GitHub: create a **Release** (tag `v0.1.0` or similar) and publish it. The **Publish to PyPI** workflow uploads the built sdist and wheel automatically.
+
+**B — Manual upload**
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Use a [PyPI API token](https://pypi.org/help/#apitoken) when `twine` prompts for credentials (or set `TWINE_USERNAME=__token__` and `TWINE_PASSWORD=pypi-...`).
+
+## Usage
+
+```text
+basicbuster --url URL (--username FILE --password FILE | --userpass FILE) [--mode MODE] [--timeout SECONDS] [--proxy URL]
+```
+
+- **`--url`**: Target URL (resource protected by HTTP Basic Auth).
+- **`--username` / `--password`**: Separate wordlists, one value per line.
+- **`--userpass`**: Combined file with `user:pass` per line (password may contain `:`; only the first `:` separates user and password).
+- **`--mode`**:
+  - `pitchfork` — pair `username[i]` with `password[i]`.
+  - `clusterbomb` — try every username with every password (default).
+- **`--timeout`**: Request timeout in seconds (default: `15`).
+- **`--quiet`**: Minimal output.
+- **`--proxy`**: Forward all traffic through an HTTP(S) proxy (e.g. Burp: `http://127.0.0.1:8080`).
+
+Successful guesses print as:
+
+```text
+[+] SUCCESS user:pass (HTTP 200)
+```
+
+### Examples
+
+Separate wordlists, clusterbomb (default):
+
+```bash
+basicbuster --url https://example.com/secret --username users.txt --password passwords.txt
+```
+
+Pitchfork (zip by line index):
+
+```bash
+basicbuster --url https://example.com/secret --username users.txt --password passwords.txt --mode pitchfork
+```
+
+Combined user:pass file:
+
+```bash
+basicbuster --url https://example.com/secret --userpass combo.txt
+```
+
+Through a local intercepting proxy:
+
+```bash
+basicbuster --url https://example.com/secret --userpass combo.txt --proxy http://127.0.0.1:8080
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

basicbuster-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+basicbuster/__init__.py,sha256=MZYK5fsWzsWA-Bi1q-BzenLsLWqDpT788_4qupZusCw,68
+basicbuster/cli.py,sha256=2EZHtgedsYvDHVUi5xtm4renOJyp-rs4F-f-f0EPzkE,1892
+basicbuster/core.py,sha256=ECGDFgs1uJS7ZcE1fKeAAihzZj7dvB2p-UdG8Z_zK4U,5738
+basicbuster-0.1.0.dist-info/licenses/LICENSE,sha256=zr5k77QlLas2jRWWi2fUzrL_ThQhwTCuU1Fo_RaK8hA,1065
+basicbuster-0.1.0.dist-info/METADATA,sha256=87W6kd_bCJmY4U7GJD9lM-Mw0e5jwnOSJjmSiPiOpTI,4209
+basicbuster-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+basicbuster-0.1.0.dist-info/entry_points.txt,sha256=OnGO_pJCVCmkGmdqOTxNWE0HgDBGiCRuPeKFARetiIg,53
+basicbuster-0.1.0.dist-info/top_level.txt,sha256=mNWro0o-3D7_0Q4iwctz4bf50-AljZI5y7b2QSvvU6I,12
+basicbuster-0.1.0.dist-info/RECORD,,

basicbuster-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

basicbuster-0.1.0.dist-info/entry_points.txt

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

basicbuster-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dhina016
+
+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.

basicbuster-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+basicbuster