Release 3.1.0

.github/dependabot.yml

@@ -2,16 +2,69 @@ version: 2
 updates:
   - package-ecosystem: "uv"
     directory: "/"
+    target-branch: "dev"
     schedule:
       interval: "weekly"
+    groups:
+      uv-minor-patch:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+      uv-major:
+        patterns:
+          - "*"
+        update-types:
+          - "major"
+  - package-ecosystem: "github-actions"
+    directory: "/"
     target-branch: "dev"
-    open-pull-requests-limit: 10
-  - package-ecosystem: github-actions
-    directory: /
+    schedule:
+      interval: "weekly"
     groups:
-      github-actions:
+      github-actions-minor-patch:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+      github-actions-major:
         patterns:
-          - "*"  # Group all Actions updates into a single larger pull request
+          - "*"
+        update-types:
+          - "major"
+  - package-ecosystem: "docker"
+    directory: "/"
+    target-branch: "dev"
     schedule:
-      interval: weekly
-    target-branch: "dev" 
+      interval: "weekly"
+    groups:
+      docker-minor-patch:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+      docker-major:
+        patterns:
+          - "*"
+        update-types:
+          - "major"
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    target-branch: "dev"
+    schedule:
+      interval: "weekly"
+    groups:
+      pre-commit-minor-patch:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+      pre-commit-major:
+        patterns:
+          - "*"
+        update-types:
+          - "major"

.github/workflows/benchmark.yml

@@ -14,10 +14,11 @@ concurrency:
 permissions:
   contents: read
   pull-requests: write
+  issues: write
 
 jobs:
   benchmark:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
 
     steps:
     - uses: actions/checkout@v7

.github/workflows/cla.yml

@@ -6,10 +6,12 @@ on:
     types: [opened, closed, synchronize]
 
 permissions:
+  contents: read
   pull-requests: write
   statuses: write
 
 jobs:
   cla:
-    uses: blacklanternsecurity/CLA/.github/workflows/cla-reusable.yml@main
+    name: check the CLA is signed
+    uses: blacklanternsecurity/CLA/.github/workflows/cla-reusable.yml@4f85d3c525483f0f846ef4384a8ece24a3c74375 # 2026-09-29
     secrets: inherit

.github/workflows/codeql.yml

@@ -21,13 +21,13 @@ on:
 
 jobs:
   analyze:
-    name: Analyze (${{ matrix.language }})
+    name: scan ${{ matrix.language }} for security issues
     # Runner size impacts CodeQL analysis time. To learn more, please see:
     #   - https://gh.io/recommended-hardware-resources-for-running-codeql
     #   - https://gh.io/supported-runners-and-hardware-resources
     #   - https://gh.io/using-larger-runners (GitHub.com only)
     # Consider using larger runners or machines with greater resources for possible analysis time improvements.
-    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-24.04' }}
     permissions:
       # required for all workflows
       security-events: write

.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,12 @@
+name: Dependabot auto-merge
+on: pull_request
+
+permissions: {}
+
+jobs:
+  auto-merge:
+    permissions:
+      contents: write
+      pull-requests: write
+      checks: read
+    uses: blacklanternsecurity/CLA/.github/workflows/dependabot-auto-merge.yml@e532142ee9e7322888f6edc80d9a89e2f8c0d96d # 2026-10-03

.github/workflows/distro_tests.yml

@@ -8,7 +8,7 @@ concurrency:
 
 jobs:
   test-distros:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     container:
       image: ${{ matrix.os }}
     strategy:
@@ -51,7 +51,10 @@ jobs:
           uv python install 3.12
           uv python pin 3.12
           uv sync --group dev
-          uv run pytest --reruns 2 --exitfirst -o timeout_func_only=true --timeout 1200 --disable-warnings --log-cli-level=INFO .
+          uv run pytest -n $(uv run python bbot/test/worker_count.py) --dist loadgroup --reruns 2 --exitfirst -o timeout_func_only=true --timeout 1200 --disable-warnings --log-cli-level=INFO \
+            bbot/test/test_step_1/test_e2e.py \
+            bbot/test/test_step_1/test_depsinstaller.py \
+            bbot/test/test_step_1/test_command.py
       - name: Upload Debug Logs
         if: always()
         uses: actions/upload-artifact@v7

.github/workflows/docs_updater.yml

@@ -7,7 +7,7 @@ on:
 
 jobs:
   update_docs:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v7
         with:

.github/workflows/tests.yml

@@ -12,7 +12,7 @@ concurrency:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     strategy:
       # if one python version fails, let the others finish
       fail-fast: false
@@ -51,9 +51,23 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./cov.xml
           verbose: true
+
+  test_matrix:
+    name: test matrix passed
+    if: always()
+    needs: [test]
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Fail unless every dependency succeeded
+        uses: re-actors/alls-green@b5b5b37504aa4183270bd3d855c52a67f212be35 # v1.3.0
+        with:
+          allowed-skips: test
+          jobs: ${{ toJSON(needs) }}
+
   publish_code:
+    name: publish package and docker images
     needs: test
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     if: github.event_name == 'push' && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/stable')
     continue-on-error: true
     steps:
@@ -200,8 +214,9 @@ jobs:
     outputs:
       BBOT_VERSION: ${{ steps.version.outputs.BBOT_VERSION }}
   tag_commit:
+    name: tag the release commit
     needs: publish_code
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     if: github.event_name == 'push' && (github.ref == 'refs/heads/stable' || github.ref == 'refs/heads/dev')
     steps:
       - uses: actions/checkout@v7
@@ -222,7 +237,7 @@ jobs:
           git push origin "$VERSION"
 
   publish_docs:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     if: github.event_name == 'push' && (github.ref == 'refs/heads/stable' || github.ref == 'refs/heads/dev')
     steps:
       - uses: actions/checkout@v7

.github/workflows/version_updater.yml

@@ -1,4 +1,4 @@
-name: Version Updater
+name: Tool Version Updater
 on:
   schedule:
     # Runs at 00:00 every day
@@ -7,7 +7,7 @@ on:
 
 jobs:
   update-nuclei-version:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v7
         with:
@@ -59,7 +59,7 @@ jobs:
           author: blsaccess <info@blacklanternsecurity.com>
           assignees: "TheTechromancer"
   update-trufflehog-version:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v7
         with:

AGENTS.md

@@ -265,7 +265,7 @@ setup()  -->  handle_event() (called many times)  -->  finish()  -->  report()
 Event types this module wants to process. The module's `handle_event()` is only called for these types.
 
 ```python
-# sslcert.py - watches for open ports to grab SSL certs from
+# fingerprintx.py - watches for open ports to fingerprint the service behind them
 watched_events = ["OPEN_TCP_PORT"]
 
 # newsletters.py - watches HTTP responses to scan HTML
@@ -302,8 +302,8 @@ Common flags:
 # crt.py - queries a third-party API, never touches the target
 flags = ["subdomain-enum", "passive"]
 
-# sslcert.py - connects directly to target ports
-flags = ["affiliates", "subdomain-enum", "email-enum", "active", "web"]
+# sslcert.py - reads certs from responses the scan already fetched
+flags = ["safe", "affiliates", "subdomain-enum", "email-enum", "active", "web"]
 ```
 
 ##### `meta` (dict)
@@ -324,27 +324,33 @@ meta = {"description": "Query API for subdomains", "auth_required": True}
 
 #### Options
 
-##### `options` / `options_desc` (dict)
-User-configurable settings. Access them via `self.config.get("option_name")`.
+##### `class Config(BaseModuleConfig)`
+User-configurable settings are declared as a nested `Config` class using pydantic fields. Access
+them via `self.config.get("option_name")`.
+
+> The legacy `options` / `options_desc` dicts are **no longer supported in BBOT 3.0+** -- a module
+> that declares them fails to load with a `CRITICAL` message.
 
 ```python
 # robots.py - configurable parsing options
-options = {"include_sitemap": False, "include_allow": True, "include_disallow": True}
-options_desc = {
-    "include_sitemap": "Include 'sitemap' entries",
-    "include_allow": "Include 'Allow' Entries",
-    "include_disallow": "Include 'Disallow' Entries",
-}
+from bbot.core.config.models import BaseModuleConfig, Field
+
+
+class robots(BaseModule):
+    class Config(BaseModuleConfig):
+        include_sitemap: bool = Field(False, description="Include 'sitemap' entries")
+        include_allow: bool = Field(True, description="Include 'Allow' Entries")
+        include_disallow: bool = Field(True, description="Include 'Disallow' Entries")
 
-# In handle_event():
-if self.config.get("include_sitemap") is True:
-    ...
+    # In handle_event():
+    #   if self.config.get("include_sitemap") is True:
+    #       ...
 ```
 
 ```python
-# sslcert.py - timeout and behavior options
-options = {"timeout": 5.0, "skip_non_ssl": True}
-options_desc = {"timeout": "Socket connect timeout in seconds", "skip_non_ssl": "Don't try common non-SSL ports"}
+# shodan_dns.py - an API key, marked sensitive and mandatory
+class Config(BaseModuleConfig):
+    api_key: str | list[str] = Field("", description="Shodan API key", sensitive=True, mandatory=True)
 ```
 
 ---
@@ -445,8 +451,8 @@ def _incoming_dedup_hash(self, event):
 How many `handle_event()` calls can run concurrently. Increase this for I/O-bound modules.
 
 ```python
-# sslcert.py - connects to many hosts in parallel
-_module_threads = 25
+# iis_shortnames.py - many short requests per host
+_module_threads = 4
 ```
 
 ##### `_batch_size` (int) -- default: `1`
@@ -480,16 +486,16 @@ _shuffle_incoming_queue = False
 Python packages to install.
 
 ```python
-# sslcert.py
-deps_pip = ["pyOpenSSL~=25.3.0"]
+# badsecrets.py
+deps_pip = ["badsecrets~=1.2.1"]
 ```
 
 ##### `deps_apt` (list)
 System packages to install.
 
 ```python
-# sslcert.py
-deps_apt = ["openssl"]
+# git_clone.py
+deps_apt = ["git"]
 ```
 
 ##### `deps_modules` (list)
@@ -595,10 +601,11 @@ async def handle_batch(self, *events):
 Called before `handle_event()`. Return `True` to accept, `False` to reject, or `(False, "reason")` to reject with a logged reason.
 
 ```python
-# sslcert.py - skip ports that don't typically use SSL
+# apkpure.py - only handle Android apps
 async def filter_event(self, event):
-    if self.skip_non_ssl and event.port in self.non_ssl_ports:
-        return False, f"Port {event.port} doesn't typically use SSL"
+    if event.type == "MOBILE_APP":
+        if "android" not in event.tags:
+            return False, "event is not an android app"
     return True
 ```
 

bbot/__init__.py

@@ -1,6 +1,31 @@
+import subprocess
+from pathlib import Path
 from importlib.metadata import version, PackageNotFoundError
 
 try:
     __version__ = version("bbot")
 except PackageNotFoundError:
     __version__ = "0.0.0"
+
+
+def _git_commit():
+    # only git checkouts have .git next to the package (a file, not a dir, in worktrees)
+    repo_root = Path(__file__).resolve().parent.parent
+    if not (repo_root / ".git").exists():
+        return None
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo_root), "describe", "--always", "--dirty", "--abbrev=9", "--exclude=*"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+_commit = _git_commit()
+__full_version__ = f"{__version__} (git:{_commit})" if _commit else __version__