stille-hunter 0.2.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.
- stille_hunter-0.2.0/.github/dependabot.yml +10 -0
- stille_hunter-0.2.0/.github/scripts/discord_payload.py +43 -0
- stille_hunter-0.2.0/.github/workflows/ci.yml +70 -0
- stille_hunter-0.2.0/.github/workflows/publish.yml +125 -0
- stille_hunter-0.2.0/.gitignore +39 -0
- stille_hunter-0.2.0/CHANGELOG.md +91 -0
- stille_hunter-0.2.0/CONTRIBUTING.md +75 -0
- stille_hunter-0.2.0/DCO +34 -0
- stille_hunter-0.2.0/LICENSE +202 -0
- stille_hunter-0.2.0/PKG-INFO +172 -0
- stille_hunter-0.2.0/README.md +143 -0
- stille_hunter-0.2.0/RELEASING.md +102 -0
- stille_hunter-0.2.0/ROADMAP.md +66 -0
- stille_hunter-0.2.0/docs/human-directed-ai-built.svg +100 -0
- stille_hunter-0.2.0/docs/icon.png +0 -0
- stille_hunter-0.2.0/docs/icon.svg +21 -0
- stille_hunter-0.2.0/docs/ledger-format.md +44 -0
- stille_hunter-0.2.0/docs/overview.svg +104 -0
- stille_hunter-0.2.0/examples/config.example.json +14 -0
- stille_hunter-0.2.0/pyproject.toml +55 -0
- stille_hunter-0.2.0/src/stille_hunter/__init__.py +9 -0
- stille_hunter-0.2.0/src/stille_hunter/check.py +332 -0
- stille_hunter-0.2.0/src/stille_hunter/cli.py +46 -0
- stille_hunter-0.2.0/src/stille_hunter/generate.py +232 -0
- stille_hunter-0.2.0/src/stille_hunter/sources/__init__.py +8 -0
- stille_hunter-0.2.0/src/stille_hunter/sources/github.py +136 -0
- stille_hunter-0.2.0/src/stille_hunter/sources/hibp.py +103 -0
- stille_hunter-0.2.0/src/stille_hunter/sources/null.py +20 -0
- stille_hunter-0.2.0/src/stille_hunter/types/__init__.py +8 -0
- stille_hunter-0.2.0/src/stille_hunter/types/api_token.py +97 -0
- stille_hunter-0.2.0/src/stille_hunter/types/aws_key.py +82 -0
- stille_hunter-0.2.0/src/stille_hunter/types/azure_credential.py +83 -0
- stille_hunter-0.2.0/src/stille_hunter/types/kubeconfig.py +116 -0
- stille_hunter-0.2.0/src/stille_hunter/types/mcp_config.py +88 -0
- stille_hunter-0.2.0/src/stille_hunter/types/member.py +370 -0
- stille_hunter-0.2.0/tests/test_check.py +81 -0
- stille_hunter-0.2.0/tests/test_generate.py +181 -0
- stille_hunter-0.2.0/tools/release.ps1 +142 -0
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""Build the Discord webhook payload announcing a stille-hunter release.
|
|
3
|
+
|
|
4
|
+
Usage: python discord_payload.py VERSION NOTES_FILE RELEASE_URL > payload.json
|
|
5
|
+
|
|
6
|
+
Discord caps a message at 2000 characters, so long release notes are cut at a
|
|
7
|
+
line boundary and point to the release page for the rest. Mentions are
|
|
8
|
+
disabled, so text like @everyone in the notes can never ping anyone.
|
|
9
|
+
"""
|
|
10
|
+
import json
|
|
11
|
+
import sys
|
|
12
|
+
|
|
13
|
+
LIMIT = 2000
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def build(version: str, notes: str, release_url: str) -> dict:
|
|
17
|
+
pypi_url = f"https://pypi.org/project/stille-hunter/{version}/"
|
|
18
|
+
head = f"**stille-hunter {version}** released\n\n"
|
|
19
|
+
tail = f"\n\nRelease notes: {release_url}\nPyPI: {pypi_url}"
|
|
20
|
+
more = "\n\n... (full notes on the release page)"
|
|
21
|
+
|
|
22
|
+
body = notes.strip()
|
|
23
|
+
room = LIMIT - len(head) - len(tail)
|
|
24
|
+
if len(body) > room:
|
|
25
|
+
room -= len(more)
|
|
26
|
+
cut = body[:room]
|
|
27
|
+
if "\n" in cut:
|
|
28
|
+
cut = cut[: cut.rindex("\n")]
|
|
29
|
+
body = cut.rstrip() + more
|
|
30
|
+
|
|
31
|
+
return {"content": head + body + tail, "allowed_mentions": {"parse": []}}
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def main(argv: list[str]) -> int:
|
|
35
|
+
version, notes_file, release_url = argv[1:4]
|
|
36
|
+
with open(notes_file, encoding="utf-8") as f:
|
|
37
|
+
notes = f.read()
|
|
38
|
+
json.dump(build(version, notes, release_url), sys.stdout, ensure_ascii=False)
|
|
39
|
+
return 0
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
if __name__ == "__main__":
|
|
43
|
+
sys.exit(main(sys.argv))
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
# CI: lint, test on every supported Python, and check DCO sign-off on PRs.
|
|
3
|
+
#
|
|
4
|
+
# Job names are required status checks on main - keep them unchanged.
|
|
5
|
+
# Third-party actions are pinned to full commit SHAs (Dependabot proposes
|
|
6
|
+
# updates) and runners are pinned, so neither can change what runs silently.
|
|
7
|
+
name: CI
|
|
8
|
+
|
|
9
|
+
on:
|
|
10
|
+
pull_request:
|
|
11
|
+
push:
|
|
12
|
+
branches: [main]
|
|
13
|
+
|
|
14
|
+
permissions:
|
|
15
|
+
contents: read
|
|
16
|
+
|
|
17
|
+
jobs:
|
|
18
|
+
lint:
|
|
19
|
+
name: ruff
|
|
20
|
+
runs-on: ubuntu-24.04
|
|
21
|
+
steps:
|
|
22
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
23
|
+
with:
|
|
24
|
+
persist-credentials: false
|
|
25
|
+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
|
|
26
|
+
with:
|
|
27
|
+
python-version: "3.12"
|
|
28
|
+
- run: pip install ruff
|
|
29
|
+
- run: ruff check .
|
|
30
|
+
|
|
31
|
+
test:
|
|
32
|
+
name: pytest (Python ${{ matrix.python-version }})
|
|
33
|
+
runs-on: ubuntu-24.04
|
|
34
|
+
strategy:
|
|
35
|
+
fail-fast: false
|
|
36
|
+
matrix:
|
|
37
|
+
python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
|
|
38
|
+
steps:
|
|
39
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
40
|
+
with:
|
|
41
|
+
persist-credentials: false
|
|
42
|
+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
|
|
43
|
+
with:
|
|
44
|
+
python-version: ${{ matrix.python-version }}
|
|
45
|
+
- run: pip install -e ".[dev]"
|
|
46
|
+
- run: pytest -q
|
|
47
|
+
|
|
48
|
+
dco:
|
|
49
|
+
name: DCO sign-off
|
|
50
|
+
if: github.event_name == 'pull_request'
|
|
51
|
+
runs-on: ubuntu-24.04
|
|
52
|
+
steps:
|
|
53
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
54
|
+
with:
|
|
55
|
+
fetch-depth: 0
|
|
56
|
+
persist-credentials: false
|
|
57
|
+
- name: Every commit must carry Signed-off-by
|
|
58
|
+
env:
|
|
59
|
+
BASE: ${{ github.event.pull_request.base.sha }}
|
|
60
|
+
HEAD: ${{ github.event.pull_request.head.sha }}
|
|
61
|
+
run: |
|
|
62
|
+
missing=0
|
|
63
|
+
for sha in $(git rev-list --no-merges "$BASE..$HEAD"); do
|
|
64
|
+
if ! git log -1 --format=%B "$sha" | grep -qE '^Signed-off-by: .+ <.+@.+>$'; then
|
|
65
|
+
echo "::error::Commit $sha has no Signed-off-by line. Fix with: git commit --amend -s (or git rebase --signoff)"
|
|
66
|
+
missing=1
|
|
67
|
+
fi
|
|
68
|
+
done
|
|
69
|
+
if [ "$missing" -eq 0 ]; then echo "All commits are signed off."; fi
|
|
70
|
+
exit $missing
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
name: Publish
|
|
3
|
+
|
|
4
|
+
# On a version tag (e.g. v0.2.0):
|
|
5
|
+
# 1. check the tag matches __version__, then build the sdist and wheel.
|
|
6
|
+
# 2. publish to PyPI via Trusted Publishing (OIDC) - no stored token.
|
|
7
|
+
# 3. create the GitHub Release from the matching CHANGELOG section.
|
|
8
|
+
# 4. announce it on Discord (only if the DISCORD_WEBHOOK secret is set).
|
|
9
|
+
#
|
|
10
|
+
# One-time PyPI setup: add a "pending publisher" at
|
|
11
|
+
# https://pypi.org/manage/account/publishing/ with:
|
|
12
|
+
# PyPI project name = stille-hunter, owner = ForexRobotics,
|
|
13
|
+
# repository = stille-hunter, workflow = publish.yml, environment = pypi
|
|
14
|
+
#
|
|
15
|
+
# One-time Discord setup (optional - the announce step is skipped without it):
|
|
16
|
+
# In the announcement channel: Edit Channel -> Integrations -> Webhooks ->
|
|
17
|
+
# New Webhook -> Copy Webhook URL. Store it as the repository secret
|
|
18
|
+
# DISCORD_WEBHOOK: gh secret set DISCORD_WEBHOOK --repo ForexRobotics/stille-hunter
|
|
19
|
+
#
|
|
20
|
+
# Third-party actions are pinned to full commit SHAs so a moved or hijacked
|
|
21
|
+
# tag cannot change what runs here; Dependabot proposes updates. Runners are
|
|
22
|
+
# pinned too, so a change to ubuntu-latest cannot alter the release build.
|
|
23
|
+
|
|
24
|
+
on:
|
|
25
|
+
push:
|
|
26
|
+
tags:
|
|
27
|
+
- "v*"
|
|
28
|
+
|
|
29
|
+
permissions:
|
|
30
|
+
contents: read
|
|
31
|
+
|
|
32
|
+
jobs:
|
|
33
|
+
build:
|
|
34
|
+
runs-on: ubuntu-24.04
|
|
35
|
+
steps:
|
|
36
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
37
|
+
with:
|
|
38
|
+
persist-credentials: false
|
|
39
|
+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
|
|
40
|
+
with:
|
|
41
|
+
python-version: "3.12"
|
|
42
|
+
- name: Tag must match __version__
|
|
43
|
+
run: |
|
|
44
|
+
VERSION=$(python -c "import re, pathlib; t = pathlib.Path('src/stille_hunter/__init__.py').read_text(); print(re.search(r'__version__ = \"(.+?)\"', t).group(1))")
|
|
45
|
+
if [ "v$VERSION" != "$GITHUB_REF_NAME" ]; then
|
|
46
|
+
echo "::error::Tag $GITHUB_REF_NAME does not match __version__ = $VERSION"
|
|
47
|
+
exit 1
|
|
48
|
+
fi
|
|
49
|
+
echo "Tag $GITHUB_REF_NAME matches __version__."
|
|
50
|
+
- name: Test before publishing
|
|
51
|
+
run: |
|
|
52
|
+
python -m pip install --upgrade pip
|
|
53
|
+
pip install -e ".[dev]"
|
|
54
|
+
pytest -q
|
|
55
|
+
- name: Build sdist and wheel
|
|
56
|
+
run: |
|
|
57
|
+
pip install build
|
|
58
|
+
python -m build
|
|
59
|
+
- name: Check metadata
|
|
60
|
+
run: |
|
|
61
|
+
pip install twine
|
|
62
|
+
twine check --strict dist/*
|
|
63
|
+
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
|
|
64
|
+
with:
|
|
65
|
+
name: dist
|
|
66
|
+
path: dist/
|
|
67
|
+
|
|
68
|
+
publish:
|
|
69
|
+
needs: build
|
|
70
|
+
runs-on: ubuntu-24.04
|
|
71
|
+
environment: pypi
|
|
72
|
+
permissions:
|
|
73
|
+
id-token: write # required for Trusted Publishing (OIDC)
|
|
74
|
+
steps:
|
|
75
|
+
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
|
|
76
|
+
with:
|
|
77
|
+
name: dist
|
|
78
|
+
path: dist/
|
|
79
|
+
- name: Publish to PyPI
|
|
80
|
+
uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
|
|
81
|
+
|
|
82
|
+
release:
|
|
83
|
+
needs: publish # only create the release once the package is live
|
|
84
|
+
runs-on: ubuntu-24.04
|
|
85
|
+
permissions:
|
|
86
|
+
contents: write # create the GitHub Release
|
|
87
|
+
steps:
|
|
88
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
89
|
+
with:
|
|
90
|
+
persist-credentials: false
|
|
91
|
+
- name: Extract release notes from CHANGELOG
|
|
92
|
+
id: notes
|
|
93
|
+
run: |
|
|
94
|
+
VERSION="${GITHUB_REF_NAME#v}"
|
|
95
|
+
# Keep a Changelog: take "## [X.Y.Z] - date" up to the next "## [" or
|
|
96
|
+
# the link references at the bottom.
|
|
97
|
+
awk -v v="## [$VERSION]" \
|
|
98
|
+
'index($0, v) == 1 {f = 1; next}
|
|
99
|
+
f && /^## \[/ {exit}
|
|
100
|
+
f && /^\[[^]]+\]: / {exit}
|
|
101
|
+
f {print}' CHANGELOG.md > notes.md
|
|
102
|
+
if [ ! -s notes.md ]; then
|
|
103
|
+
echo "See CHANGELOG.md." > notes.md
|
|
104
|
+
fi
|
|
105
|
+
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
|
|
106
|
+
- name: Create GitHub Release
|
|
107
|
+
env:
|
|
108
|
+
GH_TOKEN: ${{ github.token }}
|
|
109
|
+
TITLE: stille-hunter ${{ steps.notes.outputs.version }}
|
|
110
|
+
run: |
|
|
111
|
+
gh release create "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" \
|
|
112
|
+
--title "$TITLE" --notes-file notes.md \
|
|
113
|
+
|| gh release edit "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" \
|
|
114
|
+
--title "$TITLE" --notes-file notes.md
|
|
115
|
+
- name: Announce to Discord
|
|
116
|
+
# Runs only when the DISCORD_WEBHOOK repository secret is set.
|
|
117
|
+
env:
|
|
118
|
+
DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
|
|
119
|
+
VERSION: ${{ steps.notes.outputs.version }}
|
|
120
|
+
if: ${{ env.DISCORD_WEBHOOK != '' }}
|
|
121
|
+
run: |
|
|
122
|
+
RELEASE_URL="https://github.com/$GITHUB_REPOSITORY/releases/tag/$GITHUB_REF_NAME"
|
|
123
|
+
python3 .github/scripts/discord_payload.py "$VERSION" notes.md "$RELEASE_URL" > payload.json
|
|
124
|
+
curl -sS --fail-with-body -X POST -H "Content-Type: application/json" \
|
|
125
|
+
-d @payload.json "$DISCORD_WEBHOOK"
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# ---------------------------------------------------------------------------
|
|
2
|
+
# NEVER COMMIT THESE. They are the whole security point of the tool.
|
|
3
|
+
# ---------------------------------------------------------------------------
|
|
4
|
+
# Ledgers: the token -> seed-location map. Leaking this unmasks every canary.
|
|
5
|
+
*.ledger.json
|
|
6
|
+
*.ledger.jsonl
|
|
7
|
+
*.ledger.csv
|
|
8
|
+
# Seeded data you generated (keep it out of the repo too).
|
|
9
|
+
canary_seeded.*
|
|
10
|
+
# Real config with API keys. Commit examples/config.example.json instead.
|
|
11
|
+
config.json
|
|
12
|
+
*.config.json
|
|
13
|
+
conf.json
|
|
14
|
+
# ---------------------------------------------------------------------------
|
|
15
|
+
|
|
16
|
+
# Python
|
|
17
|
+
__pycache__/
|
|
18
|
+
*.py[cod]
|
|
19
|
+
*.egg-info/
|
|
20
|
+
.eggs/
|
|
21
|
+
build/
|
|
22
|
+
dist/
|
|
23
|
+
.venv/
|
|
24
|
+
venv/
|
|
25
|
+
env/
|
|
26
|
+
|
|
27
|
+
# Tooling
|
|
28
|
+
.pytest_cache/
|
|
29
|
+
.mypy_cache/
|
|
30
|
+
.ruff_cache/
|
|
31
|
+
.coverage
|
|
32
|
+
htmlcov/
|
|
33
|
+
|
|
34
|
+
# Editors / OS
|
|
35
|
+
.vscode/
|
|
36
|
+
.idea/
|
|
37
|
+
*.swp
|
|
38
|
+
.DS_Store
|
|
39
|
+
Thumbs.db
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to stille-hunter are documented here.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
While the version is `0.x`, minor bumps may include breaking changes; see
|
|
8
|
+
[RELEASING.md](RELEASING.md).
|
|
9
|
+
|
|
10
|
+
## [Unreleased]
|
|
11
|
+
|
|
12
|
+
## [0.2.0] - 2026-11-16
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
- New canary types, all inert and found by searching:
|
|
16
|
+
- `azure_credential` — Azure service-principal client ID, tenant ID and a
|
|
17
|
+
client secret in the current Entra format (#5).
|
|
18
|
+
- `mcp_config` — an MCP `mcpServers` config block for the GitHub or Slack
|
|
19
|
+
server with a fake token; only official `@modelcontextprotocol`
|
|
20
|
+
packages are referenced (#2).
|
|
21
|
+
- `kubeconfig` — a complete kubeconfig with a bootstrap-format token whose
|
|
22
|
+
id is the canary token, a private-address server and a fake CA blob (#3).
|
|
23
|
+
- The `github` source also searches `azure_client_id`.
|
|
24
|
+
- CI on every pull request and push to `main`: ruff lint, the test suite on
|
|
25
|
+
Python 3.10–3.14, and a DCO sign-off check on pull requests (#7).
|
|
26
|
+
- ruff configuration in `pyproject.toml` with an explicitly pinned rule set
|
|
27
|
+
(E, F, W, I, B; line length 100), and ruff in the `dev` extra.
|
|
28
|
+
- Publishing to PyPI: pushing a `vX.Y.Z` tag checks the tag against the
|
|
29
|
+
version, runs the tests, publishes with Trusted Publishing (no stored
|
|
30
|
+
token), and creates the GitHub Release from the changelog (#6).
|
|
31
|
+
- Releases are announced on Discord when a `DISCORD_WEBHOOK` secret is set:
|
|
32
|
+
version, release notes (trimmed to Discord's limit) and links, with
|
|
33
|
+
mentions disabled.
|
|
34
|
+
- Dependabot keeps the pinned GitHub Actions up to date.
|
|
35
|
+
- README badges, and PyPI classifiers for supported Python versions.
|
|
36
|
+
|
|
37
|
+
### Changed
|
|
38
|
+
- Minimum supported Python is now 3.10. Python 3.9 reached end of life in
|
|
39
|
+
October 2025 and is no longer available on current CI runners.
|
|
40
|
+
- Code tidied to pass the lint rules: sorted imports, shorter lines, a shared
|
|
41
|
+
helper for North American phone numbers, and an unused variable removed.
|
|
42
|
+
No behaviour change.
|
|
43
|
+
- GitHub Actions pinned to full commit SHAs and runners pinned to
|
|
44
|
+
`ubuntu-24.04`, so neither can change what CI runs without a review.
|
|
45
|
+
- README images and links are absolute URLs, so they also work on PyPI.
|
|
46
|
+
- `tools/release.ps1` now stops after pushing the tag; the publish workflow
|
|
47
|
+
creates the GitHub Release once the PyPI upload has succeeded.
|
|
48
|
+
|
|
49
|
+
### Fixed
|
|
50
|
+
- `api_token --provider` help named a non-existent `random` choice; the
|
|
51
|
+
option for mixing providers is `--mix`.
|
|
52
|
+
- `tools/release.ps1` read `CHANGELOG.md` in the Windows code page, which
|
|
53
|
+
would have turned non-ASCII characters into mojibake on release; it now
|
|
54
|
+
reads and writes UTF-8 explicitly.
|
|
55
|
+
|
|
56
|
+
## [0.1.0] - 2026-11-12
|
|
57
|
+
|
|
58
|
+
First tagged release. A self-contained leak-canary tool: plant realistic fake
|
|
59
|
+
records, then find them if they surface in a breach or public leak. Read-only
|
|
60
|
+
and search-only — it never touches anyone else's systems.
|
|
61
|
+
|
|
62
|
+
### Added
|
|
63
|
+
- **Canary generator** (`stille-hunter generate`) with a pluggable `CanaryType`
|
|
64
|
+
architecture — add a type by dropping a module in `stille_hunter/types/`.
|
|
65
|
+
- `member` — full fake member records: locale-consistent names, addresses,
|
|
66
|
+
phones and email domains (`--locale jp|us|gb|ca`), test-BIN card numbers
|
|
67
|
+
that can never be charged, no CVV or national IDs, adults only, with a
|
|
68
|
+
unique token woven through email / user id / password hash.
|
|
69
|
+
- `aws_key` — inert AWS access-key pairs (`AKIA...`), token embedded in the
|
|
70
|
+
tail so they can never collide with a real key.
|
|
71
|
+
- `api_token` — inert service tokens shaped like GitHub / OpenAI / Stripe /
|
|
72
|
+
Slack / generic credentials (`--provider`, `--mix`) (issue #1).
|
|
73
|
+
- **Leak checker** (`stille-hunter check`) with a pluggable `CheckSource`
|
|
74
|
+
architecture and a secret ledger mapping each token back to where it was
|
|
75
|
+
planted.
|
|
76
|
+
- `hibp` — looks canary emails up in Have I Been Pwned breaches.
|
|
77
|
+
- `github` — searches public code on GitHub for leaked secret markers
|
|
78
|
+
(keys, tokens, hashes).
|
|
79
|
+
- `null` — reference stub.
|
|
80
|
+
- `Canary.extra` carries type-specific markers so non-member canaries
|
|
81
|
+
(aws_key, api_token, ...) are searchable.
|
|
82
|
+
- Two detection paths: **inbox** (catch-all mail on a self-domain) and
|
|
83
|
+
**search** (looking tokens up in leak sources).
|
|
84
|
+
- Packaged as an installable `pip`-ready project (src layout, zero runtime
|
|
85
|
+
dependencies, `stille-hunter` CLI entry point), with a pytest suite.
|
|
86
|
+
- Apache-2.0 license; DCO sign-off contribution workflow (`DCO`,
|
|
87
|
+
`CONTRIBUTING.md`); project overview and "human-directed, AI-built" diagrams.
|
|
88
|
+
|
|
89
|
+
[Unreleased]: https://github.com/ForexRobotics/stille-hunter/compare/v0.2.0...HEAD
|
|
90
|
+
[0.2.0]: https://github.com/ForexRobotics/stille-hunter/releases/tag/v0.2.0
|
|
91
|
+
[0.1.0]: https://github.com/ForexRobotics/stille-hunter/releases/tag/v0.1.0
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Contributing to stille-hunter
|
|
2
|
+
|
|
3
|
+
Thanks for your interest in contributing. stille-hunter is **human-directed,
|
|
4
|
+
AI-built** — contributions from people and from AI assistants are both welcome,
|
|
5
|
+
and every change goes through the same gate: a pull request, CI, and human
|
|
6
|
+
review before merge.
|
|
7
|
+
|
|
8
|
+
## The one hard rule: sign off your commits (DCO)
|
|
9
|
+
|
|
10
|
+
Every commit must be signed off under the [Developer Certificate of
|
|
11
|
+
Origin](DCO) (DCO 1.1). Signing off certifies that you have the right to submit
|
|
12
|
+
the change under this project's license (Apache-2.0).
|
|
13
|
+
|
|
14
|
+
Add the sign-off automatically with the `-s` flag:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
git commit -s -m "Your message"
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
This appends a line to the commit message:
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
Signed-off-by: Your Name <your.email@example.com>
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
- The name and email become part of the public, permanent git history.
|
|
27
|
+
- The name must be a real identity (a person, or an organization you may sign
|
|
28
|
+
for) — not an anonymous handle.
|
|
29
|
+
- If you forgot to sign off, amend the last commit with
|
|
30
|
+
`git commit --amend -s`, or for several commits
|
|
31
|
+
`git rebase --signoff HEAD~<n>`.
|
|
32
|
+
|
|
33
|
+
Sign off with your own real name and email. Maintainers contributing on behalf
|
|
34
|
+
of Forex Robotics Co., Ltd. sign off under their personal name with a company
|
|
35
|
+
email, e.g. `Signed-off-by: Jane Doe <jane@forexrobotics.jp>`.
|
|
36
|
+
|
|
37
|
+
## What stille-hunter will and won't accept
|
|
38
|
+
|
|
39
|
+
stille-hunter sets a quiet trap and waits. Keep contributions inside that line:
|
|
40
|
+
|
|
41
|
+
- **Defensive and read-only.** Code may generate canaries you plant yourself,
|
|
42
|
+
and look your own canaries up in public or authorized sources. It must never
|
|
43
|
+
log into places it isn't authorized for, download or store leaked data, or
|
|
44
|
+
reach into anyone else's systems.
|
|
45
|
+
- **Standard library first.** The public package has no third-party runtime
|
|
46
|
+
dependencies. A new dependency needs a clear reason and will be discussed in
|
|
47
|
+
the PR.
|
|
48
|
+
- **New leak sources are plugins.** Add a source by subclassing `CheckSource`
|
|
49
|
+
and registering it (see `src/stille_hunter/sources/`). The frame shouldn't
|
|
50
|
+
need to change.
|
|
51
|
+
- **The ledger stays secret.** Never commit a ledger, a real `config.json`, or
|
|
52
|
+
seeded data. `.gitignore` already excludes them — keep it that way.
|
|
53
|
+
|
|
54
|
+
## Pull request flow
|
|
55
|
+
|
|
56
|
+
1. Fork and branch.
|
|
57
|
+
2. Make your change. Keep it focused.
|
|
58
|
+
3. Run the checks locally:
|
|
59
|
+
```bash
|
|
60
|
+
pip install -e ".[dev]"
|
|
61
|
+
ruff check .
|
|
62
|
+
pytest
|
|
63
|
+
```
|
|
64
|
+
4. Commit with `-s` (DCO sign-off), push, and open a pull request.
|
|
65
|
+
5. **Link the issue it resolves.** Put a closing keyword in the pull request
|
|
66
|
+
description, e.g. `Closes #12` (or `Fixes #12` / `Resolves #12`). When the PR
|
|
67
|
+
merges, GitHub closes that issue automatically and the project board moves
|
|
68
|
+
both the issue and the PR to Done.
|
|
69
|
+
6. CI runs ruff, the test suite on Python 3.10–3.14, and a DCO check that fails
|
|
70
|
+
the PR if any commit lacks `Signed-off-by`. A human reviews and merges.
|
|
71
|
+
|
|
72
|
+
## Questions
|
|
73
|
+
|
|
74
|
+
Open an issue. For anything touching what counts as "defensive," err on the
|
|
75
|
+
side of asking first.
|
stille_hunter-0.2.0/DCO
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
Developer Certificate of Origin
|
|
2
|
+
Version 1.1
|
|
3
|
+
|
|
4
|
+
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
|
|
5
|
+
|
|
6
|
+
Everyone is permitted to copy and distribute verbatim copies of this
|
|
7
|
+
license document, but changing it is not allowed.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
Developer's Certificate of Origin 1.1
|
|
11
|
+
|
|
12
|
+
By making a contribution to this project, I certify that:
|
|
13
|
+
|
|
14
|
+
(a) The contribution was created in whole or in part by me and I
|
|
15
|
+
have the right to submit it under the open source license
|
|
16
|
+
indicated in the file; or
|
|
17
|
+
|
|
18
|
+
(b) The contribution is based upon previous work that, to the best
|
|
19
|
+
of my knowledge, is covered under an appropriate open source
|
|
20
|
+
license and I have the right under that license to submit that
|
|
21
|
+
work with modifications, whether created in whole or in part
|
|
22
|
+
by me, under the same open source license (unless I am
|
|
23
|
+
permitted to submit under a different license), as indicated
|
|
24
|
+
in the file; or
|
|
25
|
+
|
|
26
|
+
(c) The contribution was provided directly to me by some other
|
|
27
|
+
person who certified (a), (b) or (c) and I have not modified
|
|
28
|
+
it.
|
|
29
|
+
|
|
30
|
+
(d) I understand and agree that this project and the contribution
|
|
31
|
+
are public and that a record of the contribution (including all
|
|
32
|
+
personal information I submit with it, including my sign-off) is
|
|
33
|
+
maintained indefinitely and may be redistributed consistent with
|
|
34
|
+
this project or the open source license(s) involved.
|