jame 1.0.dev0__py3-none-any.whl

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/__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/cli/__init__.py

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

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/core/__init__.py

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

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)