iocforge-cli 0.1.0__py3-none-any.whl

iocforge/__init__.py

@@ -0,0 +1,5 @@
+"""IOCForge: offline indicator extraction and normalization."""
+from .core import export_csv, export_json, export_stix, extract
+
+__version__ = "0.1.0"
+__all__ = ["export_csv", "export_json", "export_stix", "extract"]

iocforge/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

iocforge/cli.py

@@ -0,0 +1,40 @@
+"""Command-line entry point for IOCForge."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .core import export_csv, export_json, export_stix, extract
+
+EXPORTERS = {"json": export_json, "csv": export_csv, "stix": export_stix}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="iocforge", description="Extract threat indicators from local text files, offline.")
+    sub = parser.add_subparsers(dest="command", required=True)
+    cmd = sub.add_parser("extract", help="Extract indicators from a local report")
+    cmd.add_argument("source", help="UTF-8 text file path, or - for stdin")
+    cmd.add_argument("--format", choices=EXPORTERS, default="json")
+    cmd.add_argument("--output", "-o", help="Write output to a file (default stdout)")
+    cmd.add_argument("--include-private", action="store_true", help="Include non-global IPv4 addresses")
+    args = parser.parse_args(argv)
+    if args.command == "extract":
+        try:
+            data = sys.stdin.read() if args.source == "-" else Path(args.source).read_text(encoding="utf-8")
+            indicators = extract(data, include_private=args.include_private)
+            result = EXPORTERS[args.format](indicators)
+            if args.output:
+                Path(args.output).write_text(result, encoding="utf-8")
+                print(f"Wrote {len(indicators)} indicators to {args.output}", file=sys.stderr)
+            else:
+                sys.stdout.write(result)
+            return 0
+        except (OSError, UnicodeError) as exc:
+            print(f"iocforge: {exc}", file=sys.stderr)
+            return 1
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

iocforge/core.py

@@ -0,0 +1,140 @@
+"""Offline extraction of common indicators of compromise from untrusted text."""
+from __future__ import annotations
+
+import csv
+import io
+import ipaddress
+import json
+import re
+import uuid
+from datetime import datetime, timezone
+from urllib.parse import urlsplit, urlunsplit
+
+# Defanged notation is common in public reports. Refang before matching.
+URL_RE = re.compile(r"(?i)\bhttps?://[^\s<>\"'`]+")
+IP_RE = re.compile(r"(?<![\w.])(?:\d{1,3}\.){3}\d{1,3}(?![\w.])")
+DOMAIN_RE = re.compile(r"(?i)(?<![\w@.-])(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}(?![\w.-])")
+HASH_RE = re.compile(r"(?i)(?<![a-f0-9])(?:[a-f0-9]{64}|[a-f0-9]{40}|[a-f0-9]{32})(?![a-f0-9])")
+TRAILING = ".,;:!?)]}"
+
+
+def _refang(text: str) -> str:
+    text = re.sub(r"(?i)hxxps(?=://|\[:\]//)", "https", text)
+    text = re.sub(r"(?i)hxxp(?=://|\[:\]//)", "http", text)
+    text = re.sub(r"\[:\]", ":", text)
+    text = re.sub(r"\[\.\]|\(\.\)", ".", text)
+    return text
+
+
+def _valid_domain(value: str) -> bool:
+    return len(value) <= 253 and all(len(x) <= 63 for x in value.split("."))
+
+
+def _normalize_url(value: str) -> str | None:
+    value = value.rstrip(TRAILING)
+    try:
+        p = urlsplit(value)
+        if p.scheme.lower() not in ("http", "https") or not p.hostname:
+            return None
+        host = p.hostname.lower()
+        if not _valid_domain(host) and not _is_ip(host):
+            return None
+        # URLs with credentials are intentionally rejected to avoid exporting secrets.
+        if p.username is not None or p.password is not None:
+            return None
+        port = p.port  # May raise ValueError for invalid port.
+        netloc = host if port is None else f"{host}:{port}"
+        return urlunsplit((p.scheme.lower(), netloc, p.path or "", p.query, ""))
+    except ValueError:
+        return None
+
+
+def _is_ip(value: str) -> bool:
+    try:
+        ipaddress.ip_address(value)
+        return True
+    except ValueError:
+        return False
+
+
+def extract(text: str, *, include_private: bool = False) -> list[dict[str, str]]:
+    """Extract deduplicated indicators, without network requests or enrichment.
+
+    Default excludes non-global IPs; URLs and domains are extracted regardless of
+    DNS resolvability. This is heuristic extraction, not attribution or validation.
+    """
+    text = _refang(text)
+    found: dict[tuple[str, str], dict[str, str]] = {}
+
+    def add(kind: str, value: str) -> None:
+        found[(kind, value)] = {"type": kind, "value": value}
+
+    url_spans: list[tuple[int, int]] = []
+    for match in URL_RE.finditer(text):
+        value = _normalize_url(match.group())
+        if value:
+            add("url", value)
+            url_spans.append(match.span())
+
+    def outside_urls(start: int, end: int) -> bool:
+        return not any(start < right and end > left for left, right in url_spans)
+
+    for match in IP_RE.finditer(text):
+        if not outside_urls(*match.span()):
+            continue
+        try:
+            address = ipaddress.ip_address(match.group())
+            if include_private or address.is_global:
+                add("ipv4", str(address))
+        except ValueError:
+            continue
+
+    for match in DOMAIN_RE.finditer(text):
+        if not outside_urls(*match.span()):
+            continue
+        value = match.group().lower()
+        if _valid_domain(value) and not _is_ip(value):
+            add("domain", value)
+
+    for match in HASH_RE.finditer(text):
+        if outside_urls(*match.span()):
+            value = match.group().lower()
+            add({32: "md5", 40: "sha1", 64: "sha256"}[len(value)], value)
+
+    return [found[key] for key in sorted(found)]
+
+
+def export_json(indicators: list[dict[str, str]]) -> str:
+    return json.dumps({"schema_version": "1.0", "count": len(indicators), "indicators": indicators}, indent=2) + "\n"
+
+
+def export_csv(indicators: list[dict[str, str]]) -> str:
+    output = io.StringIO(newline="")
+    writer = csv.DictWriter(output, fieldnames=["type", "value"], lineterminator="\n")
+    writer.writeheader()
+    for item in indicators:
+        # Spreadsheet formula injection mitigation for CSV consumers.
+        value = item["value"]
+        if value.startswith(("=", "+", "-", "@", "\t", "\r")):
+            value = "'" + value
+        writer.writerow({"type": item["type"], "value": value})
+    return output.getvalue()
+
+
+_STIX_FIELDS = {"url": "url:value", "domain": "domain-name:value", "ipv4": "ipv4-addr:value", "md5": "file:hashes.MD5", "sha1": "file:hashes.'SHA-1'", "sha256": "file:hashes.'SHA-256'"}
+
+
+def export_stix(indicators: list[dict[str, str]]) -> str:
+    """Create a basic STIX 2.1 Indicator bundle; no confidence/attribution asserted."""
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    objects = []
+    for item in indicators:
+        kind, value = item["type"], item["value"]
+        if kind not in _STIX_FIELDS:
+            continue
+        safe_value = value.replace("\\", "\\\\").replace("'", "\\'")
+        pattern = f"[{_STIX_FIELDS[kind]} = '{safe_value}']"
+        stable_id = uuid.uuid5(uuid.NAMESPACE_URL, f"iocforge:{kind}:{value}")
+        objects.append({"type": "indicator", "spec_version": "2.1", "id": f"indicator--{stable_id}", "created": timestamp, "modified": timestamp, "name": f"IOCForge {kind} indicator", "pattern": pattern, "pattern_type": "stix", "valid_from": timestamp})
+    bundle = {"type": "bundle", "id": f"bundle--{uuid.uuid4()}", "objects": objects}
+    return json.dumps(bundle, indent=2) + "\n"

iocforge_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: iocforge-cli
+Version: 0.1.0
+Summary: Offline threat indicator extraction, normalization and reporting
+Author: Noir Stack LLC
+License: Proprietary Software License — Free Use, No Modification
+License-File: LICENSE
+Keywords: dfir,ioc,osint,stix,threat-intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# IOCForge
+
+Offline threat indicator extraction and normalization for incident responders, threat-intelligence analysts, and OSINT workflows.
+
+**Features:** extracts IPv4 addresses, domains, HTTP(S) URLs, MD5, SHA-1, and SHA-256 hashes; refangs common `hxxp`, `[.]`, `(.)`, and `[:]` notation; deduplicates; exports JSON, CSV, and basic STIX 2.1 Indicator bundles. Does **not** make network requests, scan hosts, or enrich indicators.
+
+## Installation
+
+Python 3.10+:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Examples
+
+```bash
+iocforge extract report.txt
+iocforge extract report.txt --format csv --output indicators.csv
+iocforge extract report.txt --format stix --output indicators.stix.json
+cat report.txt | iocforge extract - --include-private
+python -m iocforge extract report.txt
+```
+
+## Library API
+
+```python
+from iocforge import extract, export_json
+print(export_json(extract("Observed hxxps://bad[.]example/path and 8.8.8.8")))
+```
+
+## Development
+
+```bash
+python -m pytest -q
+ruff check .
+python -m build
+```
+
+## Security and limitations
+
+- Only process reports you have permission to handle. Reports may contain sensitive URLs or identifiers; review output before sharing.
+- No automatic threat verdict: a matched indicator is **not** proof of malicious activity.
+- Domain parsing is heuristic (not Public Suffix List-aware). IPv6, emails, and nested URL artifacts are not supported in v0.1.0.
+- URLs containing embedded credentials are skipped. URL fragments are removed.
+- By default, non-global IPv4 addresses are excluded; `--include-private` includes them.
+- STIX output is a minimal Indicator bundle, not a complete threat-intelligence knowledge model. Consumers should validate it against their own STIX tooling.
+- Extracted indicators are never queried or contacted by IOCForge.
+
+## Publishing
+
+Choose an available PyPI distribution name (currently configured as `iocforge-cli`), update project metadata, and configure PyPI Trusted Publishing for your repository. The release workflow publishes only on GitHub Releases.
+
+Copyright © 2026 Noir Stack LLC. Licensed under the
+[Proprietary Software License — Free Use, No Modification](LICENSE).

iocforge_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+iocforge/__init__.py,sha256=JNFDQ4pma2W8nVnUdm4Cx46Z8VP690LAr58l5Vp3m9Q,217
+iocforge/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+iocforge/cli.py,sha256=4zpXnxubz9T4Rz2uAlmXS7e8WTkUlD5ZtYuZ2RArpVE,1724
+iocforge/core.py,sha256=7uc4twWBI8F7MAFIOV29fnZCugINPoUnur5GuPbUeu4,5506
+iocforge_cli-0.1.0.dist-info/METADATA,sha256=ZvtVyd5q07SW2_d2JCZt8lgFBLBQ0Gazqd8nxtXCXOo,2808
+iocforge_cli-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+iocforge_cli-0.1.0.dist-info/entry_points.txt,sha256=5Y5yel_1thRQ3jjGSdK8ctNOH7LzMV0T1vjcqKiQ8CE,47
+iocforge_cli-0.1.0.dist-info/licenses/LICENSE,sha256=WMqIJXD3rBuirXChYblF7ipgFsKgYZR2DdUpEV-agjk,1527
+iocforge_cli-0.1.0.dist-info/RECORD,,

iocforge_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

iocforge_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+iocforge = iocforge.cli:main

iocforge_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,38 @@
+Proprietary Software License — Free Use, No Modification
+
+Copyright (c) 2026 Noir Stack LLC. All rights reserved.
+
+## 1. Grant of License
+
+The copyright holder grants users a non-exclusive, worldwide, royalty-free license to download, install, and use this software for personal, educational, research, and commercial purposes, subject to the conditions below.
+
+## 2. Restrictions
+
+Users may not, without prior written permission from the copyright holder:
+
+- Modify, adapt, translate, or create derivative works based on the software.
+- Redistribute, publish, sell, sublicense, or repackage the software.
+- Remove or alter copyright, attribution, or license notices.
+- Claim ownership or authorship of the software.
+
+## 3. Ownership
+
+All rights, title, and interest in the software, including its source code and associated intellectual property, remain with the copyright holder.
+
+No ownership rights are transferred under this license.
+
+## 4. No Warranty
+
+The software is provided "AS IS", without warranty of any kind, express or implied, to the extent permitted by applicable law.
+
+## 5. Limitation of Liability
+
+To the extent permitted by applicable law, the copyright holder shall not be liable for damages arising from the use or inability to use the software.
+
+## 6. Termination
+
+Permission to use the software terminates upon a material violation of this license, subject to applicable law.
+
+## 7. Additional Permissions
+
+Any permissions not expressly granted must be obtained in writing from the copyright holder.