Initial release of ForceHound

Author: Weylon Solis

.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: python -m pytest tests/ --ignore=tests/integration -x -q

.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: "Target repository"
+        type: choice
+        options:
+          - testpypi
+          - pypi
+        default: testpypi
+      run_tests:
+        description: "Run test suite before publish"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build-and-publish:
+    if: github.event_name == 'workflow_dispatch' && github.repository == 'NetSPI/ForceHound'
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.repository }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build
+
+      - name: Run tests
+        if: ${{ inputs.run_tests }}
+        run: |
+          python -m pip install -e ".[dev]"
+          python -m pytest tests/ -x -q
+
+      - name: Build dist
+        run: python -m build
+
+      - name: Publish to PyPI
+        if: ${{ inputs.repository == 'pypi' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Publish to TestPyPI
+        if: ${{ inputs.repository == 'testpypi' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing / coverage
+tests/
+scripts/
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+
+# ForceHound output & logs
+forcehound_output.json
+forcehound_integration_output.json
+forcehound_e2e_test.json
+forcehound_audit_*.jsonl
+forcehound_audit_*.json
+forcehound_deletions_*.json
+test_*.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude
+.claude/
+CLAUDE.md

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to ForceHound
+
+Thanks for your interest in contributing to ForceHound. Here's how to get started.
+
+## Reporting Issues
+
+When opening an issue, please include:
+
+- ForceHound version (`pip show forcehound` or check `pyproject.toml`)
+- Python version (`python --version`)
+- Collector mode used (`api`, `aura`, or `both`)
+- Steps to reproduce the issue
+- Full error output or traceback
+- Any relevant CLI flags used
+
+Do not include session IDs, access tokens, credentials, or org-identifying information in issue reports.
+
+## Development Setup
+
+```bash
+git clone https://github.com/NetSPI/ForceHound.git
+cd ForceHound
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+python -m pytest tests/ -x -q
+```
+
+## Pull Requests
+
+- Open an issue first to discuss the change
+- Create a feature branch from `main`
+- Include tests for new functionality
+- Make sure all existing tests pass before submitting
+- Keep PRs focused on a single change
+
+## Code Style
+
+- Python 3.9+ compatible
+- Type hints on function signatures
+- Docstrings on public classes and methods

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, NetSPI
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.