iocforge-cli 0.1.0__tar.gz

iocforge_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff check .
+      - run: python -m pytest -q
+      - run: python -m build

iocforge_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install release tools
+        run: python -m pip install --upgrade build twine
+      - name: Confirm the tag matches the package version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          if os.environ["RELEASE_TAG"] != f"v{version}":
+              raise SystemExit("Release tag does not match the package version.")
+          PY
+      - name: Build distributions
+        run: python -m build
+      - name: Validate distributions
+        run: twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

iocforge_cli-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/

iocforge_cli-0.1.0/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.

iocforge_cli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,55 @@
+# 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/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "iocforge-cli"
+version = "0.1.0"
+description = "Offline threat indicator extraction, normalization and reporting"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary Software License — Free Use, No Modification" }
+authors = [{name = "Noir Stack LLC"}]
+keywords = ["ioc", "threat-intelligence", "dfir", "osint", "stix"]
+classifiers = ["Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Topic :: Security"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6", "build>=1.2"]
+
+[project.scripts]
+iocforge = "iocforge.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/iocforge"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

iocforge_cli-0.1.0/src/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_cli-0.1.0/src/iocforge/__main__.py

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

iocforge_cli-0.1.0/src/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_cli-0.1.0/src/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/tests/test_core.py

@@ -0,0 +1,48 @@
+import csv
+import io
+import json
+
+from iocforge.cli import main
+from iocforge.core import export_csv, export_json, export_stix, extract
+
+
+def test_refanged_and_dedup():
+    data = "hxxps://Evil[.]example/path and hxxps://Evil[.]example/path and bad[.]example"
+    results = extract(data)
+    assert {tuple(x.values()) for x in results} == {("url", "https://evil.example/path"), ("domain", "bad.example")}
+
+
+def test_ip_validation():
+    assert {x["value"] for x in extract("8.8.8.8 999.999.999.999 192.168.1.1") if x["type"] == "ipv4"} == {"8.8.8.8"}
+    assert any(x["value"] == "192.168.1.1" for x in extract("192.168.1.1", include_private=True))
+
+
+def test_hashes():
+    values = ["a" * 32, "b" * 40, "c" * 64]
+    result = extract(" ".join(values))
+    assert {x["type"] for x in result} == {"md5", "sha1", "sha256"}
+
+
+def test_exporters():
+    items = extract("example.org 8.8.8.8")
+    assert json.loads(export_json(items))["count"] == 2
+    assert len(list(csv.DictReader(io.StringIO(export_csv(items))))) == 2
+    stix = json.loads(export_stix(items))
+    assert stix["type"] == "bundle" and len(stix["objects"]) == 2
+
+
+def test_cli(tmp_path):
+    source = tmp_path / "sample.txt"
+    target = tmp_path / "out.json"
+    source.write_text("malicious.example", encoding="utf-8")
+    assert main(["extract", str(source), "--output", str(target)]) == 0
+    assert json.loads(target.read_text())["count"] == 1
+
+
+def test_cli_missing_file(tmp_path):
+    assert main(["extract", str(tmp_path / "missing.txt")]) == 1
+
+
+def test_url_does_not_duplicate_host():
+    items = extract("https://example.com/path")
+    assert items == [{"type": "url", "value": "https://example.com/path"}]