gulp-cli 1.1.4__tar.gz → 1.1.6__tar.gz

{gulp_cli-1.1.4/src/gulp_cli.egg-info → gulp_cli-1.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gulp-cli
-Version: 1.1.4
+Version: 1.1.6
 Summary: Command-line client for gULP
 Author-email: Mentat <info@mentat.is>
 Requires-Python: >=3.12
@@ -57,6 +57,7 @@ cd gulp-cli && pip install -e .
 
 # Verify installation
 gulp-cli --help
+gulp-version
 ```
 
 ### Portable Bundles

{gulp_cli-1.1.4 → gulp_cli-1.1.6}/README.md

@@ -40,6 +40,7 @@ cd gulp-cli && pip install -e .
 
 # Verify installation
 gulp-cli --help
+gulp-version
 ```
 
 ### Portable Bundles

{gulp_cli-1.1.4 → gulp_cli-1.1.6}/docs/command-reference.md

@@ -25,6 +25,18 @@ gulp-cli --verbose --as-user USER_NAME <group> <command> ...
 
 ## Core Commands
 
+### `utility`
+
+Utility commands for gULP server metadata and similar endpoints.
+
+```bash
+gulp-cli utility gulp-version
+```
+
+`utility gulp-version` prints only the gULP version and uses the saved CLI session, so run `gulp-cli auth login` first.
+
+---
+
 ### Authentication (`auth`)
 
 #### `login`
@@ -437,20 +449,21 @@ gulp-cli operation revoke-user my_investigation alice
 Ingest one or more files into an operation.
 
 ```bash
-gulp-cli ingest file OPERATION_ID PLUGIN FILE [FILE...] [OPTIONS]
+gulp-cli ingest file OPERATION_ID PLUGIN [FILE...] [OPTIONS]
 ```
 
 **Arguments:**
 
 - `OPERATION_ID` — Target operation
 - `PLUGIN` — Plugin name (e.g., `win_evtx`, `syslog`, `csv`)
-- `FILE` — File path or glob pattern (multiple allowed)
+- `FILE` — File path or glob pattern (multiple allowed; optional when `--paths-file` is set)
 
 **Options:**
 
-- `--context-name TEXT` — Context name used for source grouping (default: `sdk_context`)
+- `--context TEXT` — Context for ingestion, specify a name to create a new context if it doesn't exist, or an existing `context_id` (default: `sdk_context`)
 - `--plugin-params TEXT` — JSON string with plugin parameters
 - `--flt TEXT` — JSON object for `GulpIngestionFilter`
+- `--paths-file PATH` — Text file with one file or glob pattern per line. When set, positional `FILE` arguments are optional and ignored if also provided.
 - `--reset-operation` — Delete and recreate the operation before ingest starts
 - `--create-operation` — Create operation automatically when it does not exist
 - `--preview` — Run preview-only ingestion (no persistence)
@@ -474,6 +487,9 @@ gulp-cli ingest file my_op win_evtx 'samples/win_evtx/*.evtx'
 # Multiple patterns
 gulp-cli ingest file my_op win_evtx '**/*.evtx' '/logs/*.json'
 
+# Paths file
+gulp-cli ingest file my_op win_evtx --paths-file /tmp/file_paths.txt
+
 # With plugin parameters
 gulp-cli ingest file my_op csv file.csv --plugin-params '{"delimiter":";","encoding":"utf-8"}'
 
@@ -494,18 +510,20 @@ gulp-cli ingest file my_op win_evtx 'samples/win_evtx/*.evtx' --wait
 Add files to an existing source.
 
 ```bash
-gulp-cli ingest file-to-source SOURCE_ID FILE [FILE...] [OPTIONS]
+gulp-cli ingest file-to-source SOURCE_ID [FILE...] [OPTIONS]
 ```
 
 **Arguments:**
 
 - `SOURCE_ID` — Source ID
-- `FILE` — File path or glob pattern (multiple allowed)
+- `FILE` — File path or glob pattern (multiple allowed; optional when `--paths-file` is set)
 
 **Options:**
 
-- `--plugin-params TEXT` — JSON object for plugin_params (overrides source defaults)
+- `--plugin TEXT` — Override the plugin associated with the source (requires `--plugin-params`)
+- `--plugin-params TEXT` — JSON object for plugin_params (overrides source defaults; required when `--plugin` is set, `{}` is allowed)
 - `--flt TEXT` — JSON object for GulpIngestionFilter
+- `--paths-file PATH` — Text file with one file or glob pattern per line. When set, positional `FILE` arguments are optional and ignored if also provided.
 - `--wait` — Wait for completion with progress
 - `--show-per-file-progress / --no-show-per-file-progress` — Show one line per completed file request in `--wait` mode (default: on)
 - `--timeout INTEGER` — Timeout in seconds for `--wait` mode
@@ -516,6 +534,8 @@ gulp-cli ingest file-to-source SOURCE_ID FILE [FILE...] [OPTIONS]
 ```bash
 gulp-cli ingest file-to-source source123 /new/System.evtx --wait
 gulp-cli ingest file-to-source source123 '/new/*.evtx'
+gulp-cli ingest file-to-source source123 --paths-file /tmp/file_paths.txt
+gulp-cli ingest file-to-source source123 /new/events.json --plugin json --plugin-params '{"mapping_parameters": {}}'
 ```
 
 ---
@@ -537,7 +557,7 @@ gulp-cli ingest zip OPERATION_ID ZIP_FILE [OPTIONS]
 
 **Options:**
 
-- `--context-name TEXT` — Context name used for source grouping (default: `sdk_context`)
+- `--context TEXT` — Context for ingestion, specify a name to create a new context if it doesn't exist, or an existing `context_id` (default: `sdk_context`)
 - `--flt TEXT` — JSON object for `GulpIngestionFilter`
 - `--create-operation` — Create operation automatically when it does not exist
 - `--wait` — Wait for completion
@@ -576,7 +596,12 @@ gulp-cli ingest zip-create OUTPUT_ZIP [PATH_PATTERN...] [OPTIONS]
 **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
+- `--no-overwrite` — Do not overwrite output ZIP if it already exists (default: overwrite enabled)
+- `--no-preserve-path` — Do not preserve the source path hierarchy inside archive entries (default: preserve path enabled)
+- `--split-size TEXT` — Create multipart ZIP volumes at this size (bytes, `kb`, `mb`, `gb`; default: disabled)
+
+When `--split-size` is set, `zip-create` writes multipart ZIP volumes such as `evidence.zip.001`, `evidence.zip.002`, etc. Extract those volumes with `7z` or another tool that supports split ZIP files.
+When `--paths-file` is set, positional `PATH_PATTERN` values are ignored. Without `--paths-file`, positional `PATH_PATTERN` values are used.
 
 **Examples:**
 
@@ -585,10 +610,10 @@ gulp-cli ingest zip-create OUTPUT_ZIP [PATH_PATTERN...] [OPTIONS]
 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
+gulp-cli ingest zip-create '$CASE_DIR/evidence.zip' '$CASE_DIR/raw/*.json' '~/pcaps/*.pcap'
 
 # Read source path expressions from a file
-gulp-cli ingest zip-create /tmp/evidence.zip --paths-file /tmp/evidence_paths.txt --overwrite
+gulp-cli ingest zip-create /tmp/evidence.zip --paths-file /tmp/evidence_paths.txt
 ```
 
 ---
@@ -1298,6 +1323,7 @@ gulp-cli enrich documents OPERATION_ID [OPTIONS]
 - `--plugin-params TEXT` — Plugin parameters JSON
 - `--flt TEXT` — Filter JSON
 - `--wait` — Wait for completion
+- `--fields TEXT` — { "field": "value" } pairs to set on enriched documents (JSON string): if "value" is `null` the enrichment is made on field's value in the document. either, enriched "value" is used.
 
 **Examples:**
 
@@ -1305,7 +1331,8 @@ gulp-cli enrich documents OPERATION_ID [OPTIONS]
 gulp-cli enrich documents my_op \
   --plugin my_enricher \
   --plugin-params '{"api_key":"..."}'  \
-  --flt '{"enriched":false}'
+  --flt '{"operation_ids":["my_op"],"source_ids":["security"]}' \
+  --fields '{"ip.destination": null}'
 ```
 
 ---
@@ -1327,12 +1354,13 @@ gulp-cli enrich single-id OPERATION_ID DOCUMENT_ID [OPTIONS]
 
 - `--plugin TEXT` — Plugin name (required)
 - `--plugin-params TEXT` — Plugin parameters JSON
+- `--fields TEXT` — { "field": "value" } pairs to set on enriched documents (JSON string): if "value" is `null` the enrichment is made on field's value in the document. either, enriched "value" is used.
 - `--wait` — Wait for completion
 
 **Examples:**
 
 ```bash
-gulp-cli enrich single-id my_op doc123 --plugin my_enricher
+gulp-cli enrich single-id my_op doc123 --plugin my_enricher --fields '{"host.os": null}' --wait
 ```
 
 ---

{gulp_cli-1.1.4 → gulp_cli-1.1.6}/docs/examples.md

@@ -45,6 +45,7 @@
     - [Run Rule on Specific Source](#run-rule-on-specific-source)
     - [Multiple Sigma Rules in Batch](#multiple-sigma-rules-in-batch)
   - [Enrichment \& Tagging Workflows](#enrichment--tagging-workflows)
+    - [use whois to enrich IP addresses with domain information](#use-whois-to-enrich-ip-addresses-with-domain-information)
     - [Tag Suspicious Events](#tag-suspicious-events)
     - [Apply Threat Level Classification](#apply-threat-level-classification)
     - [Track Analysis Progress](#track-analysis-progress)
@@ -174,8 +175,7 @@ gulp-cli ingest file incident-001 csv /data/access_log.csv \
   --plugin-params '{"delimiter":";","encoding":"iso-8859-1","has_header":true}'
 
 # 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
+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"
@@ -219,11 +219,11 @@ gulp-cli ingest zip incident-001 /evidence/evidence.zip --create-operation
 
 ```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
+gulp-cli ingest zip-create /evidence/evidence.zip /forensic/host1/*.evtx /forensic/host2 /forensic/notes.txt --no-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
+gulp-cli ingest zip-create '$CASE_ROOT/evidence.zip' '$CASE_ROOT/windows/*.evtx' '$CASE_ROOT/network/*' --no-overwrite
 
 # Build ZIP from a text file (one path expression per line)
 cat > /tmp/evidence_paths.txt <<'EOF'
@@ -613,6 +613,16 @@ done
 
 ## Enrichment & Tagging Workflows
 
+### use whois to enrich IP addresses with domain information
+
+```bash
+gulp-cli enrich documents incident-001 \
+  --plugin enrich_whois \
+  --flt '{"operation_ids":["network"]}' \
+  --fields '{"ip.destination": null}' \
+  --wait
+```
+
 ### Tag Suspicious Events
 
 ```bash

{gulp_cli-1.1.4 → gulp_cli-1.1.6}/src/gulp_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.1.4'
-__version_tuple__ = version_tuple = (1, 1, 4)
+__version__ = version = '1.1.6'
+__version_tuple__ = version_tuple = (1, 1, 6)
 
-__commit_id__ = commit_id = 'g8cbdcc79a'
+__commit_id__ = commit_id = 'g8d034cc8b'

{gulp_cli-1.1.4 → gulp_cli-1.1.6}/src/gulp_cli/cli.py

@@ -7,6 +7,7 @@ from gulp_cli.commands.auth import app as auth_app
 from gulp_cli.commands.collab import app as collab_app
 from gulp_cli.commands.context import app as context_app
 from gulp_cli.commands.db import app as db_app
+from gulp_cli.commands.enrich import app as enrich_app
 from gulp_cli.commands.enhance_map import app as enhance_map_app
 from gulp_cli.commands.glyph import app as glyph_app
 from gulp_cli.commands.ingest import app as ingest_app
@@ -14,12 +15,12 @@ from gulp_cli.commands.mapping import app as mapping_app
 from gulp_cli.commands.operations import app as operation_app
 from gulp_cli.commands.plugin import app as plugin_app
 from gulp_cli.commands.query import app as query_app
+from gulp_cli.commands.utility import app as utility_app
 from gulp_cli.commands.source import app as source_app
 from gulp_cli.commands.stats import app as stats_app
 from gulp_cli.commands.storage import app as storage_app
 from gulp_cli.commands.user_group import app as user_group_app
 from gulp_cli.commands.users import app as user_app
-from gulp_sdk.client import GulpClient
 
 from gulp_cli.config import (
     set_runtime_as_user,
@@ -27,28 +28,21 @@ from gulp_cli.config import (
     set_runtime_verbose,
 )
 from gulp_cli.extensions import load_extensions
-
-app = typer.Typer(
-    no_args_is_help=True,
-    help="Modern CLI for gULP, powered by gulp-sdk",
-)
+from gulp_cli.version import print_version
 
 
 def _show_versions(value: bool) -> None:
     if not value:
         return
 
-    from gulp_cli._version import __version__, __commit_id__
-
-    sdk_version = GulpClient("http://localhost:8080").version()
-    print(
-        f"gulp-cli version: {__version__} ({__commit_id__})"
-        if __commit_id__
-        else __version__
-    )
-    print(f"gulp-sdk version: {sdk_version}")
+    print_version()
     raise typer.Exit()
 
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Modern CLI for gULP, powered by gulp-sdk",
+)
+
 
 @app.callback(invoke_without_command=True)
 def main(
@@ -73,7 +67,7 @@ def main(
         "--version",
         callback=_show_versions,
         is_eager=True,
-        help="Show CLI and SDK versions and exit.",
+        help="Show the CLI version and exit.",
     ),
 ) -> None:
     set_runtime_config_dir(config_dir)
@@ -93,11 +87,13 @@ app.add_typer(stats_app, name="stats")
 app.add_typer(storage_app, name="storage")
 app.add_typer(collab_app, name="collab")
 app.add_typer(db_app, name="db")
+app.add_typer(enrich_app, name="enrich")
 app.add_typer(acl_app, name="acl")
 app.add_typer(plugin_app, name="plugin")
 app.add_typer(mapping_app, name="mapping")
 app.add_typer(enhance_map_app, name="enhance-map")
 app.add_typer(glyph_app, name="glyph")
+app.add_typer(utility_app, name="utility")
 
 load_extensions(
     app,
@@ -114,10 +110,12 @@ load_extensions(
         "storage": storage_app,
         "collab": collab_app,
         "db": db_app,
+        "enrich": enrich_app,
         "acl": acl_app,
         "plugin": plugin_app,
         "mapping": mapping_app,
         "enhance-map": enhance_map_app,
         "glyph": glyph_app,
+        "utility": utility_app,
     },
 )

gulp_cli-1.1.6/src/gulp_cli/commands/enrich.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import typer
+
+from gulp_cli.client import get_client
+from gulp_cli.output import print_result
+from gulp_cli.utils import comma_split, parse_json_option
+
+app = typer.Typer(help="Enrichment and tagging commands")
+
+
+@app.command("tag")
+def enrich_tag(
+    operation_id: str,
+    tags: list[str] = typer.Option(..., "--tag", help="Tag to add (repeatable)"),
+    flt: str | None = typer.Option(
+        None, "--flt", help="JSON object for GulpQueryFilter"
+    ),
+    wait: bool = typer.Option(False, "--wait", help="Wait for the async job to finish"),
+) -> None:
+    """Add tags to documents matching a filter."""
+
+    async def _run() -> None:
+        flt_parsed = parse_json_option(flt, field_name="flt")
+        async with get_client() as client:
+            result = await client.enrich.tag_documents(
+                operation_id=operation_id,
+                tags=tags,
+                flt=flt_parsed,
+                wait=wait,
+            )
+            print_result(result)
+
+    asyncio.run(_run())
+
+
+@app.command("untag")
+def enrich_untag(
+    operation_id: str,
+    tags: list[str] = typer.Option(..., "--tag", help="Tag to remove (repeatable)"),
+    flt: str | None = typer.Option(
+        None, "--flt", help="JSON object for GulpQueryFilter"
+    ),
+    wait: bool = typer.Option(False, "--wait", help="Wait for the async job to finish"),
+) -> None:
+    """Remove tags from documents matching a filter."""
+
+    async def _run() -> None:
+        flt_parsed = parse_json_option(flt, field_name="flt")
+        async with get_client() as client:
+            result = await client.enrich.untag_documents(
+                operation_id=operation_id,
+                tags=tags,
+                flt=flt_parsed,
+                wait=wait,
+            )
+            print_result(result)
+
+    asyncio.run(_run())
+
+
+@app.command("update")
+def enrich_update(
+    operation_id: str,
+    fields: str = typer.Option(..., "--fields", help="JSON object of field updates"),
+    flt: str | None = typer.Option(
+        None, "--flt", help="JSON object for GulpQueryFilter"
+    ),
+    wait: bool = typer.Option(False, "--wait", help="Wait for the async job to finish"),
+) -> None:
+    """Update fields on documents matching a filter."""
+
+    async def _run() -> None:
+        fields_parsed = parse_json_option(fields, field_name="fields")
+        if fields_parsed is None:
+            raise typer.BadParameter("--fields is required")
+        flt_parsed = parse_json_option(flt, field_name="flt")
+        async with get_client() as client:
+            result = await client.enrich.update_documents(
+                operation_id=operation_id,
+                fields=fields_parsed,
+                flt=flt_parsed,
+                wait=wait,
+            )
+            print_result(result)
+
+    asyncio.run(_run())
+
+
+@app.command("remove")
+def enrich_remove(
+    operation_id: str,
+    fields: str = typer.Option(
+        ..., "--fields", help="Comma-separated field names to remove"
+    ),
+    flt: str | None = typer.Option(
+        None, "--flt", help="JSON object for GulpQueryFilter"
+    ),
+    wait: bool = typer.Option(False, "--wait", help="Wait for the async job to finish"),
+) -> None:
+    """Remove enrichment markers or specific fields from documents matching a filter."""
+
+    async def _run() -> None:
+        flt_parsed = parse_json_option(flt, field_name="flt")
+        field_names = comma_split(fields)
+        async with get_client() as client:
+            result = await client.enrich.enrich_remove(
+                operation_id=operation_id,
+                fields=field_names or None,
+                flt=flt_parsed,
+                wait=wait,
+            )
+            print_result(result)
+
+    asyncio.run(_run())
+
+
+@app.command("documents")
+def enrich_documents(
+    operation_id: str,
+    plugin: str = typer.Option(..., "--plugin", help="Enrichment plugin name"),
+    fields: str | None = typer.Option(
+        None, "--fields", help="JSON object of fields to enrich"
+    ),
+    flt: str | None = typer.Option(
+        None, "--flt", help="JSON object for GulpQueryFilter"
+    ),
+    plugin_params: str | None = typer.Option(
+        None, "--plugin-params", help="JSON object for GulpPluginParameters"
+    ),
+    wait: bool = typer.Option(False, "--wait", help="Wait for the async job to finish"),
+) -> None:
+    """Run an enrichment plugin on documents matching a filter."""
+
+    async def _run() -> None:
+        fields_parsed = parse_json_option(fields, field_name="fields")
+        flt_parsed = parse_json_option(flt, field_name="flt")
+        plugin_params_parsed = parse_json_option(
+            plugin_params, field_name="plugin-params"
+        )
+        async with get_client() as client:
+            result = await client.enrich.enrich_documents(
+                operation_id=operation_id,
+                plugin=plugin,
+                fields=fields_parsed,
+                flt=flt_parsed,
+                plugin_params=plugin_params_parsed,
+                wait=wait,
+            )
+            print_result(result)
+
+    asyncio.run(_run())
+
+
+@app.command("single-id")
+def enrich_single_id(
+    operation_id: str,
+    doc_id: str,
+    plugin: str = typer.Option(..., "--plugin", help="Enrichment plugin name"),
+    fields: str | None = typer.Option(
+        None, "--fields", help="JSON object of fields to enrich"
+    ),
+    plugin_params: str | None = typer.Option(
+        None, "--plugin-params", help="JSON object for GulpPluginParameters"
+    ),
+) -> None:
+    """Enrich a single document by OpenSearch document ID."""
+
+    async def _run() -> None:
+        fields_parsed = parse_json_option(fields, field_name="fields")
+        plugin_params_parsed = parse_json_option(
+            plugin_params, field_name="plugin-params"
+        )
+        async with get_client() as client:
+            result = await client.enrich.enrich_single_id(
+                operation_id=operation_id,
+                doc_id=doc_id,
+                plugin=plugin,
+                fields=fields_parsed,
+                plugin_params=plugin_params_parsed,
+            )
+            print_result(result)
+
+    asyncio.run(_run())