jame 1.0.dev0__tar.gz

jame-1.0.dev0/LICENSE

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

jame-1.0.dev0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: jame
+Version: 1.0.dev0
+Summary: Just Another Method of Exploitation
+Author: JAMe Contributors
+License: MIT
+Project-URL: Homepage, https://example.com/jame
+Project-URL: Documentation, https://example.com/jame/docs
+Project-URL: Source, https://example.com/jame
+Project-URL: Issues, https://example.com/jame/issues
+Keywords: forensics,triage,security,steganography,crypto,extraction,jame
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# JAMe
+
+Just Another Method of Exploitation.
+
+JAMe is a lightweight forensic and triage toolkit for scanning files, extracting archives, identifying likely crypto patterns, checking for stegano indicators, and surfacing candidate flags in challenge files.
+
+## Overview
+
+- File type detection
+- Flag hunting with custom wildcard patterns
+- Crypto heuristics (base64/base32/base58, XOR, Caesar, Vigenere hints, hash detection)
+- Binary triage with strings, readelf, and objdump-style output
+- Steganography checks for LSB, appended ZIP, EXIF anomalies, and archive-style traces
+- Forensics triage for PDF, PCAP, and carved content
+- Archive extraction with recursive support and depth limits
+
+## Installation
+
+JAMe requires Python 3.10 or newer. From the repository root, this one-line
+installer creates the virtual environment, installs JAMe, links the command
+into the absolute path `$HOME/.local/bin`, and adds that directory to the
+current shell and future Bash login/interactive shells:
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install jame && mkdir -p "$HOME/.local/bin" && if [[ -e "$HOME/.local/bin/jame" && ! "$HOME/.local/bin/jame" -ef "$(pwd -P)/.venv/bin/jame" ]]; then printf '%s\n' 'Refusing to replace existing command at ~/.local/bin/jame' >&2; exit 1; fi && ln -sfn "$(pwd -P)/.venv/bin/jame" "$HOME/.local/bin/jame" && for rc in "$HOME/.profile" "$HOME/.bashrc"; do grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' "$rc" 2>/dev/null || printf '%s\n' 'export PATH="$HOME/.local/bin:$PATH"' >> "$rc"; done && export PATH="$HOME/.local/bin:$PATH" && jame --help
+```
+
+## CLI
+
+From a checkout, the Bash launcher can also be run directly; it uses the active
+virtual environment, the checkout's `.venv`, or `python3.10`, in that order:
+
+```bash
+./jame.sh --help
+./jame.sh tests/files/solution.txt
+```
+
+The default command finds a flag and extracts supported archives. The original
+path-only form remains supported:
+
+```bash
+./jame.sh tests/files/solution.txt
+./jame.sh solve tests/files/solution.txt --format 'flag{*}'
+```
+
+Use `*` for any-length text and `*N` for exactly `N` characters. Repeating
+unqualified asterisks does not set an exact length; for example, use `hcr{*5}`
+to require five characters, not `hcr{*****}`.
+
+Other available methods:
+
+```bash
+./jame.sh find-flag tests/files/challenge.txt --format 'hcr{*4}'
+./jame.sh scan tests/files/scan.txt
+./jame.sh crypto tests/files/strings.txt --verbose
+./jame.sh binary tests/files/strings.txt
+./jame.sh stego tests/files/strings.txt
+./jame.sh forensics tests/files/strings.txt
+./jame.sh archive path/to/archive.zip --max-depth 2
+./jame.sh file-type tests/files/strings.txt
+./jame.sh strings tests/files/strings.txt
+./jame.sh binwalk path/to/file.bin
+./jame.sh caesar 'Khoor' --shift 3
+```
+
+`--verbose` prints the structured result, including analyzer details and raw
+output where available. `binwalk` requires the external `binwalk` utility.
+
+## Quickstart
+
+### Instance API
+
+```python
+import jame
+
+engine = jame.Jame()
+result = engine.scanFile('example.bin')
+print(result.summary)
+```
+
+### Module-level API
+
+```python
+import jame
+
+result = jame.scanFile('example.bin')
+print(result.summary)
+```
+
+Module-level functions use a shared singleton engine. Configuration set through
+functions such as `jame.setFlagPatterns()` persists across subsequent module-level calls.
+
+## API Reference
+
+The camelCase API is available on `Jame` instances and as module-level functions.
+Use the instance API for independent configurations, or the module-level API to
+share one engine configuration.
+
+```python
+import jame
+
+jame.scanFile('path/to/file')
+jame.findFlag('path/to/file', 'hcr{*4}')
+jame.autoSolve('path/to/file', format='flag{*}')
+jame.cryptoAnalyze('path/to/file')
+jame.binaryAnalyze('path/to/file')
+jame.stegoAnalyze('path/to/file')
+jame.forensicsAnalyze('path/to/file')
+jame.archiveExtract('path/to/archive.zip')
+jame.decodeCaesar('uryyb', 'brute')
+```
+
+## Examples
+
+### Find a flag-like value
+
+```python
+import jame
+
+flag = jame.findFlag('notes.txt', 'hcr{*4}')
+print(flag)
+```
+
+### Run a full scan
+
+```python
+import jame
+
+scan = jame.Jame().scanFile('challenge.bin')
+print(scan.summary)
+print(scan.confidence)
+```
+
+### Decode Caesar candidates
+
+```python
+import jame
+
+result = jame.decodeCaesar('QEBJQ', 'brute') # brute is default
+print(result)
+```
+
+## License
+
+This project is licensed under the MIT License.

jame-1.0.dev0/README.md

@@ -0,0 +1,145 @@
+# JAMe
+
+Just Another Method of Exploitation.
+
+JAMe is a lightweight forensic and triage toolkit for scanning files, extracting archives, identifying likely crypto patterns, checking for stegano indicators, and surfacing candidate flags in challenge files.
+
+## Overview
+
+- File type detection
+- Flag hunting with custom wildcard patterns
+- Crypto heuristics (base64/base32/base58, XOR, Caesar, Vigenere hints, hash detection)
+- Binary triage with strings, readelf, and objdump-style output
+- Steganography checks for LSB, appended ZIP, EXIF anomalies, and archive-style traces
+- Forensics triage for PDF, PCAP, and carved content
+- Archive extraction with recursive support and depth limits
+
+## Installation
+
+JAMe requires Python 3.10 or newer. From the repository root, this one-line
+installer creates the virtual environment, installs JAMe, links the command
+into the absolute path `$HOME/.local/bin`, and adds that directory to the
+current shell and future Bash login/interactive shells:
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install jame && mkdir -p "$HOME/.local/bin" && if [[ -e "$HOME/.local/bin/jame" && ! "$HOME/.local/bin/jame" -ef "$(pwd -P)/.venv/bin/jame" ]]; then printf '%s\n' 'Refusing to replace existing command at ~/.local/bin/jame' >&2; exit 1; fi && ln -sfn "$(pwd -P)/.venv/bin/jame" "$HOME/.local/bin/jame" && for rc in "$HOME/.profile" "$HOME/.bashrc"; do grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' "$rc" 2>/dev/null || printf '%s\n' 'export PATH="$HOME/.local/bin:$PATH"' >> "$rc"; done && export PATH="$HOME/.local/bin:$PATH" && jame --help
+```
+
+## CLI
+
+From a checkout, the Bash launcher can also be run directly; it uses the active
+virtual environment, the checkout's `.venv`, or `python3.10`, in that order:
+
+```bash
+./jame.sh --help
+./jame.sh tests/files/solution.txt
+```
+
+The default command finds a flag and extracts supported archives. The original
+path-only form remains supported:
+
+```bash
+./jame.sh tests/files/solution.txt
+./jame.sh solve tests/files/solution.txt --format 'flag{*}'
+```
+
+Use `*` for any-length text and `*N` for exactly `N` characters. Repeating
+unqualified asterisks does not set an exact length; for example, use `hcr{*5}`
+to require five characters, not `hcr{*****}`.
+
+Other available methods:
+
+```bash
+./jame.sh find-flag tests/files/challenge.txt --format 'hcr{*4}'
+./jame.sh scan tests/files/scan.txt
+./jame.sh crypto tests/files/strings.txt --verbose
+./jame.sh binary tests/files/strings.txt
+./jame.sh stego tests/files/strings.txt
+./jame.sh forensics tests/files/strings.txt
+./jame.sh archive path/to/archive.zip --max-depth 2
+./jame.sh file-type tests/files/strings.txt
+./jame.sh strings tests/files/strings.txt
+./jame.sh binwalk path/to/file.bin
+./jame.sh caesar 'Khoor' --shift 3
+```
+
+`--verbose` prints the structured result, including analyzer details and raw
+output where available. `binwalk` requires the external `binwalk` utility.
+
+## Quickstart
+
+### Instance API
+
+```python
+import jame
+
+engine = jame.Jame()
+result = engine.scanFile('example.bin')
+print(result.summary)
+```
+
+### Module-level API
+
+```python
+import jame
+
+result = jame.scanFile('example.bin')
+print(result.summary)
+```
+
+Module-level functions use a shared singleton engine. Configuration set through
+functions such as `jame.setFlagPatterns()` persists across subsequent module-level calls.
+
+## API Reference
+
+The camelCase API is available on `Jame` instances and as module-level functions.
+Use the instance API for independent configurations, or the module-level API to
+share one engine configuration.
+
+```python
+import jame
+
+jame.scanFile('path/to/file')
+jame.findFlag('path/to/file', 'hcr{*4}')
+jame.autoSolve('path/to/file', format='flag{*}')
+jame.cryptoAnalyze('path/to/file')
+jame.binaryAnalyze('path/to/file')
+jame.stegoAnalyze('path/to/file')
+jame.forensicsAnalyze('path/to/file')
+jame.archiveExtract('path/to/archive.zip')
+jame.decodeCaesar('uryyb', 'brute')
+```
+
+## Examples
+
+### Find a flag-like value
+
+```python
+import jame
+
+flag = jame.findFlag('notes.txt', 'hcr{*4}')
+print(flag)
+```
+
+### Run a full scan
+
+```python
+import jame
+
+scan = jame.Jame().scanFile('challenge.bin')
+print(scan.summary)
+print(scan.confidence)
+```
+
+### Decode Caesar candidates
+
+```python
+import jame
+
+result = jame.decodeCaesar('QEBJQ', 'brute') # brute is default
+print(result)
+```
+
+## License
+
+This project is licensed under the MIT License.

jame-1.0.dev0/jame/__init__.py

@@ -0,0 +1,109 @@
+'''JAMe package.'''
+
+from jame.core.jame import Jame, create_jame
+from jame.results.binary_result import BinaryResult, BinwalkResult
+from jame.results.crypto_result import CryptoResult
+from jame.results.forensics_result import ForensicsResult
+from jame.results.scan_result import ScanResult
+from jame.results.solve_result import SolveResult
+from jame.results.stego_result import StegoResult
+
+__version__ = '0.1.0'
+_engine = Jame()
+
+
+def scanFile(path: str) -> ScanResult:
+	'''Scan a file using the shared JAMe engine.'''
+	return _engine.scanFile(path)
+
+
+def findFlag(path: str, format: str) -> str | None:
+	'''Find a matching flag using the shared JAMe engine.'''
+	return _engine.findFlag(path, format)
+
+
+def autoSolve(path: str, **ctx: object) -> SolveResult:
+	'''Run the solve workflow using the shared JAMe engine.'''
+	return _engine.autoSolve(path, **ctx)
+
+
+def cryptoAnalyze(path: str) -> CryptoResult:
+	'''Analyze file crypto indicators using the shared JAMe engine.'''
+	return _engine.cryptoAnalyze(path)
+
+
+def binaryAnalyze(path: str) -> BinaryResult:
+	'''Analyze binary indicators using the shared JAMe engine.'''
+	return _engine.binaryAnalyze(path)
+
+
+def stegoAnalyze(path: str) -> StegoResult:
+	'''Analyze steganography indicators using the shared JAMe engine.'''
+	return _engine.stegoAnalyze(path)
+
+
+def forensicsAnalyze(path: str) -> ForensicsResult:
+	'''Analyze forensic indicators using the shared JAMe engine.'''
+	return _engine.forensicsAnalyze(path)
+
+
+def archiveExtract(path: str) -> list[str]:
+	'''Extract supported archives using the shared JAMe engine.'''
+	return _engine.archiveExtract(path)
+
+
+def getFileType(path: str) -> str:
+	'''Return the file type using the shared JAMe engine.'''
+	return _engine.getFileType(path)
+
+
+def decodeCaesar(text: str, shift: int | str = 'brute') -> dict:
+	'''Decode Caesar text using the shared JAMe engine.'''
+	return _engine.decodeCaesar(text, shift)
+
+
+def setFlagPatterns(patterns: list[str]) -> None:
+	'''Set flag patterns on the shared JAMe engine.'''
+	_engine.setFlagPatterns(patterns)
+
+
+def setMaxDepth(depth: int) -> None:
+	'''Set archive extraction depth on the shared JAMe engine.'''
+	_engine.setMaxDepth(depth)
+
+
+def setVerbose(enabled: bool) -> None:
+	'''Set verbose mode on the shared JAMe engine.'''
+	_engine.setVerbose(enabled)
+
+
+def runStrings(path: str) -> list[str]:
+	'''Extract printable strings using the shared JAMe engine.'''
+	return _engine.runStrings(path)
+
+
+def runBinwalk(path: str) -> BinwalkResult:
+	'''Run binwalk using the shared JAMe engine.'''
+	return _engine.runBinwalk(path)
+
+
+__all__ = [
+	'Jame',
+	'__version__',
+	'archiveExtract',
+	'autoSolve',
+	'binaryAnalyze',
+	'create_jame',
+	'cryptoAnalyze',
+	'decodeCaesar',
+	'findFlag',
+	'forensicsAnalyze',
+	'getFileType',
+	'runBinwalk',
+	'runStrings',
+	'scanFile',
+	'setFlagPatterns',
+	'setMaxDepth',
+	'setVerbose',
+	'stegoAnalyze',
+]

jame-1.0.dev0/jame/__main__.py

@@ -0,0 +1,6 @@
+'''Allows running JAMe with python -m jame.'''
+
+from jame.cli.jame_cli import main
+
+if __name__ == '__main__':
+    main()

jame-1.0.dev0/jame/cli/__init__.py

@@ -0,0 +1 @@
+'''Command-line entry points for JAMe.'''

jame-1.0.dev0/jame/cli/jame_cli.py

@@ -0,0 +1,151 @@
+'''Command-line entry point for JAMe.'''
+
+import argparse
+import json
+import sys
+
+from jame import Jame
+
+
+_COMMANDS = {
+    'archive',
+    'binary',
+    'binwalk',
+    'caesar',
+    'crypto',
+    'file-type',
+    'find-flag',
+    'forensics',
+    'scan',
+    'solve',
+    'stego',
+    'strings',
+}
+
+
+def _add_path_arguments(command: argparse.ArgumentParser) -> None:
+    command.add_argument('path', help='Path to the file to analyze')
+    command.add_argument('--verbose', action='store_true', help='Print structured result details')
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog='jame',
+        description='Just Another Method of Exploitation',
+    )
+    subparsers = parser.add_subparsers(dest='command', required=True)
+
+    solve = subparsers.add_parser('solve', help='Find a flag and extract supported archives')
+    _add_path_arguments(solve)
+    solve.add_argument(
+        '--format',
+        default='flag{*}',
+        help="Flag pattern; '*' matches any length and '*N' matches exactly N characters",
+    )
+    solve.add_argument('--max-depth', type=int, default=3, help='Archive extraction depth')
+
+    find_flag = subparsers.add_parser('find-flag', help='Find a flag matching a pattern')
+    _add_path_arguments(find_flag)
+    find_flag.add_argument(
+        '--format',
+        default='flag{*}',
+        help="Flag pattern; '*' matches any length and '*N' matches exactly N characters",
+    )
+
+    for name, description in (
+        ('scan', 'Run all available analyzers'),
+        ('crypto', 'Analyze crypto indicators'),
+        ('binary', 'Analyze binary indicators'),
+        ('stego', 'Check for steganography indicators'),
+        ('forensics', 'Run forensic checks'),
+        ('file-type', 'Detect the file type'),
+        ('strings', 'Extract printable strings'),
+        ('binwalk', 'Run binwalk when installed'),
+    ):
+        command = subparsers.add_parser(name, help=description)
+        _add_path_arguments(command)
+
+    archive = subparsers.add_parser('archive', help='Extract supported archives')
+    _add_path_arguments(archive)
+    archive.add_argument('--max-depth', type=int, default=3, help='Archive extraction depth')
+
+    caesar = subparsers.add_parser('caesar', help='Decode Caesar-shifted text')
+    caesar.add_argument('text', help='Text to decode')
+    caesar.add_argument('--shift', default='brute', help="Integer shift or 'brute'")
+    caesar.add_argument('--verbose', action='store_true', help='Print structured result details')
+
+    return parser
+
+
+def _print_result(result: object, verbose: bool) -> None:
+    if verbose:
+        to_dict = getattr(result, 'to_dict', None)
+        output = to_dict() if callable(to_dict) else result
+        print(json.dumps(output, indent=2, default=str))
+    elif hasattr(result, 'summary'):
+        print(result.summary)
+    elif result is None:
+        print('No flag found.')
+    elif isinstance(result, list):
+        print('\n'.join(str(item) for item in result) if result else 'No results.')
+    elif isinstance(result, (dict, tuple)):
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        print(result)
+
+
+def main() -> None:
+    '''Parse command-line options and run the requested JAMe method.'''
+    argv = sys.argv[1:]
+    if argv and argv[0] not in _COMMANDS and argv[0] not in {'-h', '--help'}:
+        argv.insert(0, 'solve')
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    max_depth = getattr(args, 'max_depth', 3)
+    engine = Jame(
+        flag_patterns=[getattr(args, 'format', 'flag{*}')],
+        max_depth=max_depth,
+        verbose=args.verbose,
+    )
+
+    if args.command == 'solve':
+        result = engine.autoSolve(
+            args.path,
+            format=args.format,
+            maxDepth=args.max_depth,
+            verbose=args.verbose,
+        )
+    elif args.command == 'find-flag':
+        result = engine.findFlag(args.path, args.format)
+    elif args.command == 'scan':
+        result = engine.scanFile(args.path)
+    elif args.command == 'crypto':
+        result = engine.cryptoAnalyze(args.path)
+    elif args.command == 'binary':
+        result = engine.binaryAnalyze(args.path)
+    elif args.command == 'stego':
+        result = engine.stegoAnalyze(args.path)
+    elif args.command == 'forensics':
+        result = engine.forensicsAnalyze(args.path)
+    elif args.command == 'archive':
+        engine.setMaxDepth(args.max_depth)
+        result = engine.archiveExtract(args.path)
+    elif args.command == 'file-type':
+        result = engine.getFileType(args.path)
+    elif args.command == 'strings':
+        result = engine.runStrings(args.path)
+    elif args.command == 'binwalk':
+        result = engine.runBinwalk(args.path)
+    else:
+        try:
+            shift = 'brute' if args.shift == 'brute' else int(args.shift)
+        except ValueError:
+            parser.error("--shift must be an integer or 'brute'")
+        result = engine.decodeCaesar(args.text, shift)
+
+    _print_result(result, args.verbose)
+
+
+if __name__ == '__main__':
+    main()

jame-1.0.dev0/jame/core/__init__.py

@@ -0,0 +1,5 @@
+'''Core library API for JAMe.'''
+
+from jame.core.jame import Jame
+
+__all__ = ['Jame']

jame-1.0.dev0/jame/core/filetype.py

@@ -0,0 +1,69 @@
+'''File type helpers for JAMe.'''
+
+import os
+
+
+def detect_file_type_from_bytes(data: bytes) -> str:
+    '''Return a best-effort file type label from the file header.'''
+    if len(data) >= 4 and data[:4] == b'\x7fELF':
+        return 'ELF binary'
+    if data.startswith(b'PK'):
+        return 'ZIP archive'
+    if data.startswith(b'\x1f\x8b'):
+        return 'GZIP compressed data'
+    if data.startswith(b'%PDF'):
+        return 'PDF document'
+    if data.startswith(b'\x89PNG'):
+        return 'PNG image'
+    if data.startswith(b'GIF8'):
+        return 'GIF image'
+    if data.startswith(b'RIFF') and data[8:12] == b'WAVE':
+        return 'WAV audio'
+    if data.startswith(b'\xff\xd8\xff'):
+        return 'JPEG image'
+    if data.startswith(b'#!'):
+        return 'script'
+    return 'unknown binary'
+
+
+def get_file_type(path: str) -> str:
+    '''Return a string label for a file based on extension and file header.'''
+    if not os.path.exists(path):
+        return 'missing'
+
+    _, ext = os.path.splitext(path)
+    ext = ext.lower()
+    lookup = {
+        '.zip': 'ZIP archive',
+        '.jar': 'JAR archive',
+        '.tar': 'TAR archive',
+        '.gz': 'GZIP archive',
+        '.bz2': 'BZIP2 archive',
+        '.xz': 'XZ archive',
+        '.pdf': 'PDF document',
+        '.png': 'PNG image',
+        '.jpg': 'JPEG image',
+        '.jpeg': 'JPEG image',
+        '.gif': 'GIF image',
+        '.pcap': 'PCAP capture',
+        '.pcapng': 'PCAPNG capture',
+        '.exe': 'PE binary',
+        '.dll': 'DLL binary',
+        '.so': 'shared object',
+        '.bin': 'binary blob',
+        '.txt': 'text file',
+        '.csv': 'CSV file',
+        '.py': 'Python source',
+        '.html': 'HTML document',
+        '.json': 'JSON document',
+        '.xml': 'XML document',
+    }
+    if ext in lookup:
+        return lookup[ext]
+
+    try:
+        with open(path, 'rb') as handle:
+            data = handle.read(256)
+    except OSError:
+        return 'unknown'
+    return detect_file_type_from_bytes(data)