lure-analyze 0.2.0__tar.gz

lure_analyze-0.2.0/LICENSE

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

lure_analyze-0.2.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: lure-analyze
+Version: 0.2.0
+Summary: Local Linux binary analysis tool for security researchers and CTF players
+Author-email: Usman Ismail <0xusmanismail@proton.me>
+License: MIT
+Project-URL: Homepage, https://github.com/0xusmanismail/lure
+Project-URL: Repository, https://github.com/0xusmanismail/lure
+Project-URL: Issues, https://github.com/0xusmanismail/lure/issues
+Keywords: security,malware,sandbox,linux,binary-analysis,strace,elf,ctf,reverse-engineering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.7
+Requires-Dist: pyelftools>=0.30
+Dynamic: license-file
+
+# lure
+
+> Local Linux binary analysis. Zero cloud. Zero root. Zero cost.
+
+⚠️ **Early development (v0.2.0).** Core features (`inspect`, `run`,
+`diff`) work end to end on x86_64 Linux. This is a young project —
+expect rough edges, limited error handling on unusual inputs, and
+missing features. Bug reports, feedback, and contributions are very
+welcome. Network isolation is enforced. Filesystem isolation is
+not — run inside a VM when analyzing untrusted samples.
+
+![Lure dangerous verdict](assets/dangerous-3.png)
+
+## What it does
+
+Lure runs an untrusted Linux binary in a lightweight monitoring
+environment (user + network namespaces + strace) and tells you
+exactly what it did — which files it touched, what network
+connections it tried, what processes it spawned — then gives you a
+plain verdict: **CLEAN**, **SUSPICIOUS**, or **DANGEROUS**.
+
+Everything happens on your machine. Nothing is uploaded anywhere.
+
+## Why
+
+- **Privacy** — sensitive or client samples never leave your machine
+- **Zero setup** — no VM, no Docker, no Cuckoo install process
+- **Readable** — structured reports instead of raw strace noise
+- **Free** — MIT licensed, runs on tools already on Kali Linux
+
+## Isolation model
+
+Lure uses Linux user and network namespaces to prevent the binary
+from making outbound network connections. The host filesystem
+remains visible to the analyzed binary. For stronger isolation
+(mount namespace, seccomp, cgroups), run Lure inside a VM or
+container. Lure is primarily a behavioral observation tool, not a
+hardened sandbox.
+
+## Install
+
+```bash
+git clone https://github.com/0xusmanismail/lure.git
+cd lure
+pip install -e . --break-system-packages
+```
+
+The `--break-system-packages` flag is required on Arch Linux and on
+recent Debian/Ubuntu releases, which restrict installing into the
+system Python environment by default (PEP 668).
+
+Requires `strace` and `unshare` installed.
+
+## Usage
+
+### Inspect a binary
+
+```bash
+lure inspect /bin/ls
+```
+
+Reads ELF headers, architecture, security mitigations, linked libraries, and file hashes — without executing a single byte of code.
+
+![inspect](assets/inspect-1.png)
+
+### Run a binary in the sandbox
+
+```bash
+lure run ./suspicious_binary
+```
+
+Live feed of file access, network attempts, and spawned processes, followed by a full behavioral report.
+
+![run live feed](assets/run-1.png)
+
+![run report](assets/run-2.png)
+
+### Catch suspicious behavior
+
+```bash
+lure run ./demo_dangerous
+```
+
+Sensitive file access combined with network activity trips a DANGEROUS verdict, with the exact triggers listed.
+
+![dangerous analysis](assets/dangerous-1.png)
+
+![dangerous report](assets/dangerous-2.png)
+
+![dangerous verdict](assets/dangerous-3.png)
+
+### Compare two runs with lure diff
+
+```bash
+lure run --save /bin/ls
+lure run --save /bin/echo
+lure diff report1.json report2.json
+```
+
+Shows new/removed files, new connections, verdict changes, and syscall count differences between two saved runs.
+
+![diff output](assets/diff-1.png)
+
+### Save a report
+
+```bash
+lure run --save ./binary
+```
+
+Saves the full report to `~/.lure/reports/` as both a plain-text `.txt` file and a structured `.json` file.
+
+## Status & Roadmap
+
+**Working now:**
+- ELF inspection with security mitigation detection
+- Sandboxed execution via `unshare` + `strace`
+- Live event feed during execution
+- Full behavioral report with CLEAN/SUSPICIOUS/DANGEROUS verdict
+- Verdict shows exact triggering files and IPs
+- Report saving (plain text + JSON)
+- Report comparison via `lure diff`
+- Non-ELF file detection with clean error messages
+- Works on Arch Linux, Kali, Debian, Ubuntu
+
+**Planned:**
+- Demo GIF showing live execution
+- PyPI package (`pip install lure-analyze`)
+- Packaged releases
+
+## License
+
+MIT — see [LICENSE](LICENSE)

lure_analyze-0.2.0/README.md

@@ -0,0 +1,132 @@
+# lure
+
+> Local Linux binary analysis. Zero cloud. Zero root. Zero cost.
+
+⚠️ **Early development (v0.2.0).** Core features (`inspect`, `run`,
+`diff`) work end to end on x86_64 Linux. This is a young project —
+expect rough edges, limited error handling on unusual inputs, and
+missing features. Bug reports, feedback, and contributions are very
+welcome. Network isolation is enforced. Filesystem isolation is
+not — run inside a VM when analyzing untrusted samples.
+
+![Lure dangerous verdict](assets/dangerous-3.png)
+
+## What it does
+
+Lure runs an untrusted Linux binary in a lightweight monitoring
+environment (user + network namespaces + strace) and tells you
+exactly what it did — which files it touched, what network
+connections it tried, what processes it spawned — then gives you a
+plain verdict: **CLEAN**, **SUSPICIOUS**, or **DANGEROUS**.
+
+Everything happens on your machine. Nothing is uploaded anywhere.
+
+## Why
+
+- **Privacy** — sensitive or client samples never leave your machine
+- **Zero setup** — no VM, no Docker, no Cuckoo install process
+- **Readable** — structured reports instead of raw strace noise
+- **Free** — MIT licensed, runs on tools already on Kali Linux
+
+## Isolation model
+
+Lure uses Linux user and network namespaces to prevent the binary
+from making outbound network connections. The host filesystem
+remains visible to the analyzed binary. For stronger isolation
+(mount namespace, seccomp, cgroups), run Lure inside a VM or
+container. Lure is primarily a behavioral observation tool, not a
+hardened sandbox.
+
+## Install
+
+```bash
+git clone https://github.com/0xusmanismail/lure.git
+cd lure
+pip install -e . --break-system-packages
+```
+
+The `--break-system-packages` flag is required on Arch Linux and on
+recent Debian/Ubuntu releases, which restrict installing into the
+system Python environment by default (PEP 668).
+
+Requires `strace` and `unshare` installed.
+
+## Usage
+
+### Inspect a binary
+
+```bash
+lure inspect /bin/ls
+```
+
+Reads ELF headers, architecture, security mitigations, linked libraries, and file hashes — without executing a single byte of code.
+
+![inspect](assets/inspect-1.png)
+
+### Run a binary in the sandbox
+
+```bash
+lure run ./suspicious_binary
+```
+
+Live feed of file access, network attempts, and spawned processes, followed by a full behavioral report.
+
+![run live feed](assets/run-1.png)
+
+![run report](assets/run-2.png)
+
+### Catch suspicious behavior
+
+```bash
+lure run ./demo_dangerous
+```
+
+Sensitive file access combined with network activity trips a DANGEROUS verdict, with the exact triggers listed.
+
+![dangerous analysis](assets/dangerous-1.png)
+
+![dangerous report](assets/dangerous-2.png)
+
+![dangerous verdict](assets/dangerous-3.png)
+
+### Compare two runs with lure diff
+
+```bash
+lure run --save /bin/ls
+lure run --save /bin/echo
+lure diff report1.json report2.json
+```
+
+Shows new/removed files, new connections, verdict changes, and syscall count differences between two saved runs.
+
+![diff output](assets/diff-1.png)
+
+### Save a report
+
+```bash
+lure run --save ./binary
+```
+
+Saves the full report to `~/.lure/reports/` as both a plain-text `.txt` file and a structured `.json` file.
+
+## Status & Roadmap
+
+**Working now:**
+- ELF inspection with security mitigation detection
+- Sandboxed execution via `unshare` + `strace`
+- Live event feed during execution
+- Full behavioral report with CLEAN/SUSPICIOUS/DANGEROUS verdict
+- Verdict shows exact triggering files and IPs
+- Report saving (plain text + JSON)
+- Report comparison via `lure diff`
+- Non-ELF file detection with clean error messages
+- Works on Arch Linux, Kali, Debian, Ubuntu
+
+**Planned:**
+- Demo GIF showing live execution
+- PyPI package (`pip install lure-analyze`)
+- Packaged releases
+
+## License
+
+MIT — see [LICENSE](LICENSE)

lure_analyze-0.2.0/lure/__init__.py

@@ -0,0 +1,12 @@
+# FILE: lure/__init__.py
+"""
+Lure — local Linux binary analysis tool.
+
+Runs untrusted ELF binaries and shows exactly what they did.
+Files accessed. Network attempts. Processes spawned.
+Zero cloud upload. Zero root. Zero cost.
+"""
+
+__version__ = "0.2.0"
+__author__  = "Lure"
+__license__ = "MIT"

lure_analyze-0.2.0/lure/diff.py

@@ -0,0 +1,123 @@
+# FILE: lure/diff.py
+"""
+Report comparison engine for 'lure diff'.
+Compares two JSON reports produced by 'lure run --save' and shows
+what changed between the two runs.
+"""
+
+import json
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+from rich import box
+
+console = Console()
+
+
+# ── Loading ───────────────────────────────────────────────────────────────────
+
+def _load_report(path):
+    """Load and parse a JSON report. Returns (data, error_message)."""
+    p = Path(path)
+    if not p.exists():
+        return None, f'file not found: {path}'
+    try:
+        with open(p, 'r') as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError) as exc:
+        return None, f'invalid JSON report — {exc}'
+    return data, None
+
+
+# ── Panels ────────────────────────────────────────────────────────────────────
+
+def _list_panel(title, items, style):
+    if not items:
+        body = Text('  (none)', style='dim italic')
+    else:
+        body = Text()
+        for item in items:
+            body.append(f'  • {item}\n', style=style)
+    return Panel(
+        body,
+        title=f'[bold]{title}[/bold] ({len(items)})',
+        border_style='dim white',
+        box=box.ROUNDED,
+        padding=(0, 1),
+    )
+
+
+# ── Main entry point ──────────────────────────────────────────────────────────
+
+def run_diff(report1_path, report2_path):
+    """Full report comparison — called by the 'lure diff' command."""
+
+    r1, err1 = _load_report(report1_path)
+    if err1:
+        console.print(f'[red]Error:[/red] {report1_path} — {err1}')
+        return
+
+    r2, err2 = _load_report(report2_path)
+    if err2:
+        console.print(f'[red]Error:[/red] {report2_path} — {err2}')
+        return
+
+    console.print(Panel.fit(
+        f'[bold magenta]DIFF[/bold magenta]  '
+        f'[white]{Path(report1_path).name}[/white] '
+        f'[dim]→[/dim] [white]{Path(report2_path).name}[/white]',
+        border_style='magenta',
+        box=box.ROUNDED,
+    ))
+
+    # ── Files ──────────────────────────────────────────────────────────────────
+    files1 = set(r1.get('files_accessed', []))
+    files2 = set(r2.get('files_accessed', []))
+    new_files     = sorted(files2 - files1)
+    removed_files = sorted(files1 - files2)
+
+    console.print(_list_panel('New Files',     new_files,     'green'))
+    console.print(_list_panel('Removed Files', removed_files, 'red'))
+
+    # ── Network ────────────────────────────────────────────────────────────────
+    net1 = {(n['ip'], n['port']) for n in r1.get('network_attempts', [])}
+    net2 = {(n['ip'], n['port']) for n in r2.get('network_attempts', [])}
+    new_conns = sorted(f'{ip}:{port}' for ip, port in (net2 - net1))
+
+    console.print(_list_panel('New Connections', new_conns, 'cyan'))
+
+    # ── Verdict ────────────────────────────────────────────────────────────────
+    verdict1 = r1.get('verdict', '?')
+    verdict2 = r2.get('verdict', '?')
+
+    if verdict1 != verdict2:
+        verdict_text = Text.assemble(
+            (verdict1, 'bold'), ('  →  ', 'dim'), (verdict2, 'bold'),
+        )
+    else:
+        verdict_text = Text.assemble((verdict2, 'bold'), ('  (unchanged)', 'dim'))
+
+    console.print(Panel(
+        verdict_text,
+        title='[bold]Verdict[/bold]',
+        border_style='dim white',
+        box=box.ROUNDED,
+        padding=(0, 1),
+    ))
+
+    # ── Syscalls ───────────────────────────────────────────────────────────────
+    sc1   = r1.get('syscall_total', 0)
+    sc2   = r2.get('syscall_total', 0)
+    delta = sc2 - sc1
+    sign  = '+' if delta >= 0 else ''
+
+    console.print(Panel(
+        Text(f'  {sign}{delta} syscalls  ({sc1} → {sc2})'),
+        title='[bold]Syscall Count[/bold]',
+        border_style='dim white',
+        box=box.ROUNDED,
+        padding=(0, 1),
+    ))
+    console.print()