gulp-cli 1.0.8__tar.gz → 1.1.1__tar.gz

gulp_cli-1.1.1/.github/workflows/portable-bundles.yml

@@ -0,0 +1,127 @@
+name: Portable bundles
+
+"on":
+  push:
+    tags: ['v*', 'test-v*']
+  workflow_dispatch: {}
+
+jobs:
+  build-portable:
+    name: Build portable bundle (${{ matrix.bundle_name }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 90
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            bundle_name: gulp-cli-portable-linux-x64
+            launcher_path: portable/launch-linux.sh
+          - os: windows-latest
+            bundle_name: gulp-cli-portable-windows-x64
+            launcher_path: portable/launch-windows.bat
+          - os: macos-14
+            bundle_name: gulp-cli-portable-macos-arm64
+            launcher_path: portable/launch-macos.sh
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install . pyinstaller
+
+      - name: Build executable
+        run: |
+          pyinstaller --noconfirm --clean gulp-cli.spec
+
+      - name: Assemble portable layout
+        shell: python
+        env:
+          BUNDLE_NAME: ${{ matrix.bundle_name }}
+          LAUNCHER_PATH: ${{ matrix.launcher_path }}
+        run: |
+          import os
+          import shutil
+          from pathlib import Path
+
+          dist_dir = Path("dist")
+          source_dir = dist_dir / "gulp-cli"
+          bundle_dir = dist_dir / os.environ["BUNDLE_NAME"]
+          launcher_path = Path(os.environ["LAUNCHER_PATH"])
+
+          if bundle_dir.exists():
+              shutil.rmtree(bundle_dir)
+
+          shutil.copytree(source_dir, bundle_dir)
+          (bundle_dir / "data" / "extension").mkdir(parents=True, exist_ok=True)
+          shutil.copy2(launcher_path, bundle_dir / launcher_path.name)
+          shutil.copy2("README.md", bundle_dir / "README.md")
+
+      - name: Upload portable artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.bundle_name }}
+          path: dist/${{ matrix.bundle_name }}
+          if-no-files-found: error
+
+  build-portable-macos-x64:
+    name: Build portable bundle (gulp-cli-portable-macos-x64)
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: macos-15-intel
+    timeout-minutes: 90
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install . pyinstaller
+
+      - name: Build executable
+        run: |
+          pyinstaller --noconfirm --clean gulp-cli.spec
+
+      - name: Assemble portable layout
+        shell: python
+        env:
+          BUNDLE_NAME: gulp-cli-portable-macos-x64
+          LAUNCHER_PATH: portable/launch-macos.sh
+        run: |
+          import os
+          import shutil
+          from pathlib import Path
+
+          dist_dir = Path("dist")
+          source_dir = dist_dir / "gulp-cli"
+          bundle_dir = dist_dir / os.environ["BUNDLE_NAME"]
+          launcher_path = Path(os.environ["LAUNCHER_PATH"])
+
+          if bundle_dir.exists():
+              shutil.rmtree(bundle_dir)
+
+          shutil.copytree(source_dir, bundle_dir)
+          (bundle_dir / "data" / "extension").mkdir(parents=True, exist_ok=True)
+          shutil.copy2(launcher_path, bundle_dir / launcher_path.name)
+          shutil.copy2("README.md", bundle_dir / "README.md")
+
+      - name: Upload portable artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: gulp-cli-portable-macos-x64
+          path: dist/gulp-cli-portable-macos-x64
+          if-no-files-found: error

{gulp_cli-1.0.8 → gulp_cli-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gulp-cli
-Version: 1.0.8
+Version: 1.1.1
 Summary: Command-line client for gULP
 Author-email: Mentat <info@mentat.is>
 Requires-Python: >=3.12
@@ -9,6 +9,8 @@ Requires-Dist: typer==0.23.1
 Requires-Dist: rich==15.0.0
 Requires-Dist: click==8.3.3
 Requires-Dist: gulp-sdk
+Provides-Extra: portable
+Requires-Dist: pyinstaller<7,>=6.11; extra == "portable"
 
 # 🚀 gulp-cli
 
@@ -41,6 +43,9 @@ All with **beautiful terminal output**, **automatic tab completion**, and **asyn
 # from pip
 pip install gulp-cli
 
+# or install local portable-build tooling
+pip install 'gulp-cli[portable]'
+
 # or, for the latest development version:
 python3 -m venv ./.venv
 source ./.venv/bin/activate
@@ -51,10 +56,20 @@ cd gulp-cli && pip install -e .
 gulp-cli --help
 ```
 
+### Portable Bundles
+
+For offline use from a USB stick, prefer the OS-specific portable bundles built with PyInstaller instead of `pip install`.
+
+- Each target OS needs its own bundle: Linux, Windows, macOS Intel, macOS Apple Silicon.
+- Portable bundles keep config and external extensions in a local `data/` directory next to the executable.
+- You can override that location with `GULP_CLI_HOME` or `--config-dir`.
+
+See **[Portable Usage](./docs/portable.md)** for the layout, local build command, and CI artifact details.
+
 ### Basic Usage
 
 > for the cli to work, set `"ws_ignore_missing": true` (should be default in the v1.6.51 backend, though ...) in your `gulp_cfg.json` to prevent the backend from halting operations when the CLI disconnects its websocket after sending an async request!
- 
+
 ```bash
 # Login to your gULP instance
 gulp-cli auth login --url http://localhost:8080 --username admin --password admin
@@ -71,6 +86,7 @@ gulp-cli ingest file my_operation win_evtx 'samples/win_evtx/*.evtx'
 # Query documents
 gulp-cli query raw my_operation --q '{"query":{"match_all":{}}}'
 ```
+
 ---
 
 ## 📚 Documentation
@@ -78,6 +94,7 @@ gulp-cli query raw my_operation --q '{"query":{"match_all":{}}}'
 - **[Getting Started Guide](./docs/getting-started.md)** — auth, first operation, first ingest
 - **[Command Reference](./docs/command-reference.md)** — all available commands and options
 - **[Extensions Guide](./docs/extensions.md)** — dynamic extension loading and custom command contract
+- **[Portable Usage](./docs/portable.md)** — offline bundles and USB-friendly layout
 - **[Resource Management Commands](./docs/resource-management.md)** — context, source, plugin, mapping, enhance-map, glyph
 - **[Practical Examples](./docs/examples.md)** — real-world workflows and recipes
 - **[Troubleshooting](./docs/troubleshooting-cli.md)** — common issues and solutions

gulp_cli-1.0.8/src/gulp_cli.egg-info/PKG-INFO → gulp_cli-1.1.1/README.md

@@ -1,15 +1,3 @@
-Metadata-Version: 2.4
-Name: gulp-cli
-Version: 1.0.8
-Summary: Command-line client for gULP
-Author-email: Mentat <info@mentat.is>
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-Requires-Dist: typer==0.23.1
-Requires-Dist: rich==15.0.0
-Requires-Dist: click==8.3.3
-Requires-Dist: gulp-sdk
-
 # 🚀 gulp-cli
 
 **A modern, powerful command-line interface for gULP** — manage forensic document ingestion, querying, enrichment, and collaboration entirely from your terminal.
@@ -41,6 +29,9 @@ All with **beautiful terminal output**, **automatic tab completion**, and **asyn
 # from pip
 pip install gulp-cli
 
+# or install local portable-build tooling
+pip install 'gulp-cli[portable]'
+
 # or, for the latest development version:
 python3 -m venv ./.venv
 source ./.venv/bin/activate
@@ -51,10 +42,20 @@ cd gulp-cli && pip install -e .
 gulp-cli --help
 ```
 
+### Portable Bundles
+
+For offline use from a USB stick, prefer the OS-specific portable bundles built with PyInstaller instead of `pip install`.
+
+- Each target OS needs its own bundle: Linux, Windows, macOS Intel, macOS Apple Silicon.
+- Portable bundles keep config and external extensions in a local `data/` directory next to the executable.
+- You can override that location with `GULP_CLI_HOME` or `--config-dir`.
+
+See **[Portable Usage](./docs/portable.md)** for the layout, local build command, and CI artifact details.
+
 ### Basic Usage
 
 > for the cli to work, set `"ws_ignore_missing": true` (should be default in the v1.6.51 backend, though ...) in your `gulp_cfg.json` to prevent the backend from halting operations when the CLI disconnects its websocket after sending an async request!
- 
+
 ```bash
 # Login to your gULP instance
 gulp-cli auth login --url http://localhost:8080 --username admin --password admin
@@ -71,6 +72,7 @@ gulp-cli ingest file my_operation win_evtx 'samples/win_evtx/*.evtx'
 # Query documents
 gulp-cli query raw my_operation --q '{"query":{"match_all":{}}}'
 ```
+
 ---
 
 ## 📚 Documentation
@@ -78,6 +80,7 @@ gulp-cli query raw my_operation --q '{"query":{"match_all":{}}}'
 - **[Getting Started Guide](./docs/getting-started.md)** — auth, first operation, first ingest
 - **[Command Reference](./docs/command-reference.md)** — all available commands and options
 - **[Extensions Guide](./docs/extensions.md)** — dynamic extension loading and custom command contract
+- **[Portable Usage](./docs/portable.md)** — offline bundles and USB-friendly layout
 - **[Resource Management Commands](./docs/resource-management.md)** — context, source, plugin, mapping, enhance-map, glyph
 - **[Practical Examples](./docs/examples.md)** — real-world workflows and recipes
 - **[Troubleshooting](./docs/troubleshooting-cli.md)** — common issues and solutions

{gulp_cli-1.0.8 → gulp_cli-1.1.1}/docs/command-reference.md

@@ -520,6 +520,8 @@ gulp-cli ingest file-to-source source123 '/new/*.evtx'
 
 Ingest from a ZIP archive.
 
+> TO BE DEPRECATED...
+
 ```bash
 gulp-cli ingest zip OPERATION_ID ZIP_FILE [OPTIONS]
 ```
@@ -527,7 +529,7 @@ gulp-cli ingest zip OPERATION_ID ZIP_FILE [OPTIONS]
 **Arguments:**
 
 - `OPERATION_ID` — Target operation
-- `ZIP_FILE` — Path to ZIP file
+- `ZIP_FILE` — Path to ZIP file containing a `metadata.json` in the root, describing the content as specified in gulp's `ingest_zip` docs.
 
 **Options:**
 
@@ -546,6 +548,47 @@ gulp-cli ingest zip my_op /data/evidence.zip --create-operation
 
 ---
 
+#### `zip-create`
+
+Create a ZIP archive from one or more source path expressions.
+
+Path expressions may be:
+
+- a single file path
+- a directory path
+- a glob mask (for example `/bla/somef*.txt`, `/bla/*`, `**/*.evtx`)
+
+Environment variables and home shortcuts are expanded in all input paths (for example `$EVIDENCE_DIR/*.evtx`, `~/cases/case-01/*`).
+
+```bash
+gulp-cli ingest zip-create OUTPUT_ZIP [PATH_PATTERN...] [OPTIONS]
+```
+
+**Arguments:**
+
+- `OUTPUT_ZIP` — Destination ZIP path (supports environment variables and `~`)
+- `PATH_PATTERN` — File, directory, or glob path expression (multiple allowed)
+
+**Options:**
+
+- `--paths-file TEXT` — Text file with one source path expression per line (supports environment variables and `~` per line)
+- `--overwrite` — Overwrite output ZIP if it already exists
+
+**Examples:**
+
+```bash
+# Create a ZIP from mixed path expressions
+gulp-cli ingest zip-create /tmp/evidence.zip /data/host1/*.evtx /data/host2 /data/readme.txt
+
+# Use environment variables and home shortcuts
+gulp-cli ingest zip-create '$CASE_DIR/evidence.zip' '$CASE_DIR/raw/*.json' '~/pcaps/*.pcap' --overwrite
+
+# Read source path expressions from a file
+gulp-cli ingest zip-create /tmp/evidence.zip --paths-file /tmp/evidence_paths.txt --overwrite
+```
+
+---
+
 #### `raw`
 
 Ingest raw payload chunks into an operation.

{gulp_cli-1.0.8 → gulp_cli-1.1.1}/docs/examples.md

@@ -9,6 +9,7 @@
     - [JSON Logs Ingestion](#json-logs-ingestion)
     - [Add More Evidence to Existing Source](#add-more-evidence-to-existing-source)
     - [ZIP Archive Ingestion](#zip-archive-ingestion)
+    - [Create ZIP Archive from Paths and Masks](#create-zip-archive-from-paths-and-masks)
     - [Raw Payload Ingestion](#raw-payload-ingestion)
   - [Request Stats Monitoring Workflows](#request-stats-monitoring-workflows)
     - [Monitor Ongoing Requests (Live)](#monitor-ongoing-requests-live)
@@ -175,6 +176,10 @@ gulp-cli ingest file incident-001 csv /data/access_log.csv \
 # pass mapping directly without using a mapping file
 gulp-cli ingest file test_operation csv ./samples/mftecmd/sample_record.csv --plugin-params '{ "mapping_parameters": { "mappings": { "test
 _mapping": { "fields": { "Created0x10": { "ecs": [ "@timestamp" ] } } } } } }' --reset-operation --wait
+
+# pass mapping using a gulp mapping file with mapping_id to specify which mapping to use in the file
+gulp-cli ingest file test_operation csv ./samples/mftecmd/sample_record.csv --plugin-params '{ "mapping_parameters"
+: { "mapping_file": "mftecmd_csv.json", "mapping_id": "record" } }' --wait --reset-operation
 ```
 
 ### JSON Logs Ingestion
@@ -210,6 +215,29 @@ gulp-cli ingest zip incident-001 /evidence/evidence.zip --wait
 gulp-cli ingest zip incident-001 /evidence/evidence.zip --create-operation
 ```
 
+### Create ZIP Archive from Paths and Masks
+
+```bash
+# Build ZIP from mixed sources: file, directory, and wildcard mask
+gulp-cli ingest zip-create /evidence/evidence.zip /forensic/host1/*.evtx /forensic/host2 /forensic/notes.txt --overwrite
+
+# Use environment variables and ~ in source expressions and output path
+export CASE_ROOT=~/cases/incident-001
+gulp-cli ingest zip-create '$CASE_ROOT/evidence.zip' '$CASE_ROOT/windows/*.evtx' '$CASE_ROOT/network/*' --overwrite
+
+# Build ZIP from a text file (one path expression per line)
+cat > /tmp/evidence_paths.txt <<'EOF'
+$CASE_ROOT/windows/*.evtx
+$CASE_ROOT/linux/**/*.log
+~/captures/*.pcap
+EOF
+
+gulp-cli ingest zip-create '$CASE_ROOT/evidence.zip' --paths-file /tmp/evidence_paths.txt --overwrite
+
+# Then ingest the generated ZIP
+gulp-cli ingest zip incident-001 '$CASE_ROOT/evidence.zip' --wait
+```
+
 ### Raw Payload Ingestion
 
 ```bash

gulp_cli-1.1.1/docs/portable.md

@@ -0,0 +1,76 @@
+# Portable gulp-cli
+
+Portable bundles are the recommended way to run `gulp-cli` from removable media or on machines without internet access.
+
+## What portable means here
+
+- You build one bundle per target OS and architecture.
+- The bundle already contains Python, `gulp-cli`, `gulp-sdk`, and runtime dependencies.
+- User state lives in a local `data/` folder instead of the user profile.
+
+There is no single executable that runs unchanged on Linux, Windows, and macOS. Build and ship one artifact for each platform:
+
+- Linux `x86_64`
+- Windows `x86_64`
+- macOS `x86_64`
+- macOS `arm64`
+
+## Portable layout
+
+The CI workflow produces a directory like this:
+
+```text
+gulp-cli-portable-<platform>/
+  gulp-cli[.exe]
+  _internal/
+  launch-linux.sh | launch-macos.sh | launch-windows.bat
+  data/
+    extension/
+  README.md
+```
+
+`gulp-cli` automatically uses `./data` when running from a frozen bundle and that directory exists.
+
+## Runtime overrides
+
+The CLI supports both of these overrides:
+
+```bash
+GULP_CLI_HOME=/path/to/portable-data gulp-cli auth whoami
+gulp-cli --config-dir /path/to/portable-data auth whoami
+```
+
+The overridden directory stores:
+
+- `config.json`
+- `extension/`
+
+## Local build
+
+Build a portable bundle locally from the repo root:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install '.[portable]'
+pyinstaller --noconfirm --clean gulp-cli.spec
+```
+
+The output is written under `dist/gulp-cli/`.
+
+## Notes for offline USB use
+
+- Build bundles on CI or on a machine with internet access first.
+- Copy the resulting platform-specific bundle folders to the USB stick.
+- The target machine does not need Python or internet access.
+- The target machine still needs network connectivity to the gULP server unless that server is local.
+
+## GitHub Actions
+
+The repository includes a matrix workflow that builds portable artifacts for:
+
+- Linux `x86_64`
+- Windows `x86_64`
+- macOS `x86_64`
+- macOS `arm64`
+
+Artifacts are uploaded from `.github/workflows/portable-bundles.yml`.