cycode 3.13.0__tar.gz → 3.13.1.dev1__tar.gz

{cycode-3.13.0 → cycode-3.13.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cycode
-Version: 3.13.0
+Version: 3.13.1.dev1
 Summary: Boost security in your dev lifecycle via SAST, SCA, Secrets & IaC scanning.
 License-Expression: MIT
 License-File: LICENCE
@@ -62,7 +62,11 @@ This guide walks you through both installation and usage.
     2. [Available Options](#available-options)
     3. [MCP Tools](#mcp-tools)
     4. [Usage Examples](#usage-examples)
-5. [Scan Command](#scan-command)
+5. [Platform Command](#platform-command-beta)
+    1. [Discovering Commands](#discovering-commands)
+    2. [Examples](#platform-examples)
+    3. [Notes & Limitations](#platform-notes--limitations)
+6. [Scan Command](#scan-command)
     1. [Running a Scan](#running-a-scan)
         1. [Options](#options)
            1. [Severity Threshold](#severity-option)
@@ -646,6 +650,64 @@ This information can be helpful when:
 - Debugging transport-specific issues
 
 
+# Platform Command \[BETA\]
+
+> [!WARNING]
+> The `platform` command is in **beta**. Commands, arguments, and output formats are generated dynamically from the Cycode API spec and may change between releases without notice. Do not rely on them in production automation yet.
+
+The `cycode platform` command exposes the Cycode platform's read APIs as CLI commands. It groups endpoints by resource (e.g. `projects`, `violations`, `workflows`) and turns each endpoint's parameters into typed CLI arguments and `--option` flags.
+
+```bash
+cycode platform projects list --page-size 50
+cycode platform violations count
+cycode platform workflows view <workflow-id>
+```
+
+The OpenAPI spec is fetched from the Cycode API on first use and cached at `~/.cycode/openapi-spec.json` for 24 hours. Unrelated commands (`cycode scan`, `cycode status`, etc.) do not trigger a fetch.
+
+> [!NOTE]
+> You must be authenticated (`cycode auth` or `CYCODE_CLIENT_ID` / `CYCODE_CLIENT_SECRET` environment variables) for `cycode platform` to discover and run commands. Other Cycode CLI commands work without authentication.
+
+## Discovering Commands
+
+Because commands are generated from the spec, the source of truth for what's available is `--help`:
+
+```bash
+cycode platform --help                  # list all resource groups
+cycode platform projects --help         # list actions on a resource
+cycode platform projects list --help    # list options/arguments for an action
+```
+
+## Platform Examples
+
+```bash
+# List projects with pagination
+cycode platform projects list --page-size 25
+
+# View a single project by ID
+cycode platform projects view <project-id>
+
+# Count violations across the tenant
+cycode platform violations count
+
+# Filter using query parameters (see `--help` for what each endpoint supports)
+cycode platform violations list --severity CRITICAL
+```
+
+All output is JSON by default — pipe it through `jq` for ad-hoc filtering:
+
+```bash
+cycode platform projects list --page-size 100 | jq '.items[].name'
+```
+
+## Platform Notes & Limitations
+
+- **Read-only today.** Only `GET` endpoints are exposed in this beta.
+- **Spec-driven.** Adding a new endpoint to the API surfaces it automatically the next time the cache is refreshed.
+- **No bundled spec.** The first `cycode platform` invocation after install (or after the 24h cache expires) performs a network fetch. On slow connections this first call may take a few seconds; subsequent calls are near-instant until the cache expires.
+- **Override the cache TTL** with `CYCODE_SPEC_CACHE_TTL=<seconds>`.
+
+
 # Scan Command
 
 ## Running a Scan

{cycode-3.13.0 → cycode-3.13.1.dev1}/README.md

@@ -21,7 +21,11 @@ This guide walks you through both installation and usage.
     2. [Available Options](#available-options)
     3. [MCP Tools](#mcp-tools)
     4. [Usage Examples](#usage-examples)
-5. [Scan Command](#scan-command)
+5. [Platform Command](#platform-command-beta)
+    1. [Discovering Commands](#discovering-commands)
+    2. [Examples](#platform-examples)
+    3. [Notes & Limitations](#platform-notes--limitations)
+6. [Scan Command](#scan-command)
     1. [Running a Scan](#running-a-scan)
         1. [Options](#options)
            1. [Severity Threshold](#severity-option)
@@ -605,6 +609,64 @@ This information can be helpful when:
 - Debugging transport-specific issues
 
 
+# Platform Command \[BETA\]
+
+> [!WARNING]
+> The `platform` command is in **beta**. Commands, arguments, and output formats are generated dynamically from the Cycode API spec and may change between releases without notice. Do not rely on them in production automation yet.
+
+The `cycode platform` command exposes the Cycode platform's read APIs as CLI commands. It groups endpoints by resource (e.g. `projects`, `violations`, `workflows`) and turns each endpoint's parameters into typed CLI arguments and `--option` flags.
+
+```bash
+cycode platform projects list --page-size 50
+cycode platform violations count
+cycode platform workflows view <workflow-id>
+```
+
+The OpenAPI spec is fetched from the Cycode API on first use and cached at `~/.cycode/openapi-spec.json` for 24 hours. Unrelated commands (`cycode scan`, `cycode status`, etc.) do not trigger a fetch.
+
+> [!NOTE]
+> You must be authenticated (`cycode auth` or `CYCODE_CLIENT_ID` / `CYCODE_CLIENT_SECRET` environment variables) for `cycode platform` to discover and run commands. Other Cycode CLI commands work without authentication.
+
+## Discovering Commands
+
+Because commands are generated from the spec, the source of truth for what's available is `--help`:
+
+```bash
+cycode platform --help                  # list all resource groups
+cycode platform projects --help         # list actions on a resource
+cycode platform projects list --help    # list options/arguments for an action
+```
+
+## Platform Examples
+
+```bash
+# List projects with pagination
+cycode platform projects list --page-size 25
+
+# View a single project by ID
+cycode platform projects view <project-id>
+
+# Count violations across the tenant
+cycode platform violations count
+
+# Filter using query parameters (see `--help` for what each endpoint supports)
+cycode platform violations list --severity CRITICAL
+```
+
+All output is JSON by default — pipe it through `jq` for ad-hoc filtering:
+
+```bash
+cycode platform projects list --page-size 100 | jq '.items[].name'
+```
+
+## Platform Notes & Limitations
+
+- **Read-only today.** Only `GET` endpoints are exposed in this beta.
+- **Spec-driven.** Adding a new endpoint to the API surfaces it automatically the next time the cache is refreshed.
+- **No bundled spec.** The first `cycode platform` invocation after install (or after the 24h cache expires) performs a network fetch. On slow connections this first call may take a few seconds; subsequent calls are near-instant until the cache expires.
+- **Override the cache TTL** with `CYCODE_SPEC_CACHE_TTL=<seconds>`.
+
+
 # Scan Command
 
 ## Running a Scan

cycode-3.13.1.dev1/cycode/__init__.py

@@ -0,0 +1 @@
+__version__ = '3.13.1.dev1'  # DON'T TOUCH. Placeholder. Will be filled automatically on poetry build from Git Tag

{cycode-3.13.0 → cycode-3.13.1.dev1}/cycode/cli/app.py

@@ -2,6 +2,7 @@ import logging
 import sys
 from typing import Annotated, Optional
 
+import click
 import typer
 from typer import rich_utils
 from typer._completion_classes import completion_init
@@ -10,6 +11,7 @@ from typer.completion import install_callback, show_callback
 
 from cycode import __version__
 from cycode.cli.apps import ai_guardrails, ai_remediation, auth, configure, ignore, report, report_import, scan, status
+from cycode.cli.apps.api import get_platform_group
 
 if sys.version_info >= (3, 10):
     from cycode.cli.apps import mcp
@@ -56,6 +58,27 @@ app.add_typer(status.app)
 if sys.version_info >= (3, 10):
     app.add_typer(mcp.app)
 
+# Register the `platform` command group (dynamically built from the OpenAPI spec).
+# The group itself is constructed cheaply at import time; the spec is only fetched
+# when the user actually invokes `cycode platform ...`. Unrelated commands like
+# `cycode scan` and `cycode status` never trigger a spec fetch.
+#
+# Typer doesn't support adding native Click groups directly, so we monkey-patch
+# typer.main.get_group to inject our `platform` group into the resolved Click group.
+# The `app_typer is app` guard ensures we only modify our own app.
+_platform_group = get_platform_group()
+_original_get_group = typer.main.get_group
+
+
+def _get_group_with_platform(app_typer: typer.Typer) -> click.Group:
+    group = _original_get_group(app_typer)
+    if app_typer is app and _platform_group.name not in group.commands:
+        group.add_command(_platform_group, _platform_group.name)
+    return group
+
+
+typer.main.get_group = _get_group_with_platform
+
 
 def check_latest_version_on_close(ctx: typer.Context) -> None:
     output = ctx.obj.get('output')

cycode-3.13.1.dev1/cycode/cli/apps/api/__init__.py

@@ -0,0 +1,69 @@
+"""Cycode platform API CLI commands.
+
+Dynamically builds CLI command groups from the Cycode API v4 OpenAPI spec.
+The spec is fetched lazily — only when the user invokes `cycode platform ...` —
+and cached locally for 24 hours.
+"""
+
+from typing import Any, Optional
+
+import click
+
+from cycode.logger import get_logger
+
+logger = get_logger('Platform')
+
+_PLATFORM_HELP = (
+    '[BETA] Access the Cycode platform.\n\n'
+    'Commands are generated dynamically from the Cycode API spec and may change '
+    'between releases. The spec is fetched on first use and cached for 24 hours.'
+)
+
+
+class PlatformGroup(click.Group):
+    """Lazy-loading Click group for `cycode platform` subcommands.
+
+    The OpenAPI spec is only fetched when the user actually invokes
+    `cycode platform ...` (or asks for its help). Unrelated commands like
+    `cycode scan` or `cycode status` never trigger a spec fetch.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._loaded: bool = False
+
+    def _ensure_loaded(self, ctx: Optional[click.Context]) -> None:
+        if self._loaded:
+            return
+        self._loaded = True  # set first to avoid re-entrancy on errors
+
+        client_id = client_secret = None
+        if ctx is not None:
+            root = ctx.find_root()
+            if root.obj:
+                client_id = root.obj.get('client_id')
+                client_secret = root.obj.get('client_secret')
+
+        try:
+            from cycode.cli.apps.api.api_command import build_api_command_groups
+
+            for sub_group, name in build_api_command_groups(client_id, client_secret):
+                if name not in self.commands:
+                    self.add_command(sub_group, name)
+        except Exception as e:
+            logger.debug('Could not load platform commands: %s', e)
+            # Surface the error to the user only when they're inside `platform`
+            click.echo(f'Error loading Cycode platform commands: {e}', err=True)
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        self._ensure_loaded(ctx)
+        return super().list_commands(ctx)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> Optional[click.Command]:
+        self._ensure_loaded(ctx)
+        return super().get_command(ctx, cmd_name)
+
+
+def get_platform_group() -> click.Group:
+    """Return the top-level `platform` Click group (lazy-loading)."""
+    return PlatformGroup(name='platform', help=_PLATFORM_HELP, no_args_is_help=True)

cycode-3.13.1.dev1/cycode/cli/apps/api/api_command.py

@@ -0,0 +1,271 @@
+"""OpenAPI-to-Typer translator: dynamically builds CLI commands from the Cycode API v4 spec."""
+
+import json
+import re
+from typing import Any, Optional
+
+import click
+
+from cycode.cli.apps.api.openapi_spec import OpenAPISpecError, get_openapi_spec, parse_spec_commands
+from cycode.logger import get_logger
+
+logger = get_logger('API Command')
+
+# Map OpenAPI parameter types to Click types
+_CLICK_TYPE_MAP: dict[str, click.ParamType] = {
+    'string': click.STRING,
+    'integer': click.INT,
+    'number': click.FLOAT,
+    'boolean': click.BOOL,
+}
+
+
+def _normalize_tag(tag: str) -> str:
+    """Normalize an OpenAPI tag to a CLI-friendly command name.
+
+    'Scan Statistics' -> 'scan-statistics'
+    'CLI scan statistics' -> 'cli-scan-statistics'
+    """
+    return re.sub(r'[^a-z0-9]+', '-', tag.lower()).strip('-')
+
+
+def _find_common_prefix(paths: list[str]) -> str:
+    """Find the longest common path prefix shared by all paths."""
+    if not paths:
+        return ''
+    if len(paths) == 1:
+        # For single-path tags, use the parent directory as prefix
+        return '/'.join(paths[0].split('/')[:-1])
+
+    common = paths[0]
+    for p in paths[1:]:
+        while not p.startswith(common + '/') and common != p:
+            common = '/'.join(common.split('/')[:-1])
+    return common
+
+
+def _path_to_command_name(path: str, common_prefix: str, has_path_params: bool) -> str:
+    """Derive a CLI command name from an API path relative to the tag's common prefix.
+
+    Rules:
+    1. Strip the common prefix shared by all endpoints in the tag
+    2. Remove path parameter segments ({id})
+    3. If nothing remains: 'list' (no path params) or 'view' (has path params)
+    4. Otherwise: use remaining segments joined with hyphens
+
+    Examples:
+        /v4/projects          (prefix=/v4/projects)  -> list
+        /v4/projects/{id}     (prefix=/v4/projects)  -> view
+        /v4/projects/assets   (prefix=/v4/projects)  -> assets
+        /v4/violations/count  (prefix=/v4/violations) -> count
+    """
+    # Strip common prefix
+    relative = path[len(common_prefix) :] if path.startswith(common_prefix) else path
+    relative = relative.strip('/')
+
+    # Remove path parameter segments and empty parts
+    parts = [p for p in relative.split('/') if p and not p.startswith('{')]
+
+    if not parts:
+        return 'view' if has_path_params else 'list'
+
+    # Join remaining segments with hyphens, normalize to kebab-case
+    return re.sub(r'[^a-z0-9]+', '-', '-'.join(parts).lower()).strip('-')
+
+
+def _param_to_option_name(name: str) -> str:
+    """Convert an OpenAPI parameter name to a CLI option name.
+
+    'page_size' -> '--page-size'
+    'pageSize' -> '--page-size'
+    'filter.status' -> '--filter-status'
+    """
+    s = re.sub(r'([a-z])([A-Z])', r'\1-\2', name)
+    # Replace any non-alphanumeric characters with hyphens
+    s = re.sub(r'[^a-z0-9]+', '-', s.lower()).strip('-')
+    return f'--{s}'
+
+
+def _make_api_request(
+    endpoint_path: str,
+    method: str,
+    path_params: dict[str, str],
+    query_params: dict[str, Any],
+    client_id: Optional[str] = None,
+    client_secret: Optional[str] = None,
+) -> dict:
+    """Execute an API request using the CLI's standard auth client."""
+    from urllib.parse import quote
+
+    from cycode.cli.apps.api.openapi_spec import resolve_credentials
+    from cycode.cyclient.cycode_token_based_client import CycodeTokenBasedClient
+
+    cid, csecret = resolve_credentials(client_id, client_secret)
+    client = CycodeTokenBasedClient(cid, csecret)
+
+    # Substitute path parameters (URL-encoded to prevent path traversal)
+    url_path = endpoint_path
+    for param_name, param_value in path_params.items():
+        url_path = url_path.replace(f'{{{param_name}}}', quote(str(param_value), safe=''))
+
+    filtered_query = {k: v for k, v in query_params.items() if v is not None}
+
+    response = client.get(url_path.lstrip('/'), params=filtered_query)
+    return response.json()
+
+
+def build_api_command_groups(
+    client_id: Optional[str] = None,
+    client_secret: Optional[str] = None,
+) -> list[tuple[click.Group, str]]:
+    """Build Click command groups from the OpenAPI spec.
+
+    Returns a list of (click_group, command_name) tuples.
+    """
+    try:
+        spec = get_openapi_spec(client_id, client_secret)
+    except OpenAPISpecError as e:
+        logger.warning('Could not load OpenAPI spec: %s', e)
+        return []
+
+    groups = parse_spec_commands(spec)
+    result = []
+
+    for tag, endpoints in groups.items():
+        tag_name = _normalize_tag(tag)
+
+        group = click.Group(name=tag_name, help=f'[BETA] {tag}')
+
+        # Compute common prefix from all GET (non-deprecated) endpoint paths in this tag
+        get_endpoints = [ep for ep in endpoints if ep['method'] == 'get' and not ep.get('deprecated')]
+        if not get_endpoints:
+            continue
+
+        clean_paths = [re.sub(r'/\{[^}]+\}', '', ep['path']) for ep in get_endpoints]
+        common_prefix = _find_common_prefix(clean_paths)
+
+        used_names: dict[str, int] = {}
+
+        for endpoint in get_endpoints:
+            has_path_params = bool(endpoint['path_params'])
+            cmd_name = _path_to_command_name(endpoint['path'], common_prefix, has_path_params)
+
+            # Fix redundancy: if command name matches the tag name, use list/view
+            # e.g. "cycode groups groups" -> "cycode groups list"
+            if cmd_name == tag_name:
+                cmd_name = 'view' if has_path_params else 'list'
+
+            # Handle duplicate names (e.g. deprecated + new endpoint for same resource)
+            if cmd_name in used_names:
+                used_names[cmd_name] += 1
+                cmd_name = f'{cmd_name}-v{used_names[cmd_name]}'
+            else:
+                used_names[cmd_name] = 1
+
+            cmd = _build_endpoint_command(cmd_name, endpoint)
+            group.add_command(cmd, cmd_name)
+
+        result.append((group, tag_name))
+
+    return result
+
+
+def _build_click_params(endpoint: dict) -> list[click.Parameter]:
+    """Build Click parameters from OpenAPI endpoint definition."""
+    params: list[click.Parameter] = []
+
+    # Path parameters -> required arguments
+    for p in endpoint['path_params']:
+        param_type = _CLICK_TYPE_MAP.get(p.get('schema', {}).get('type', 'string'), click.STRING)
+        params.append(
+            click.Argument(
+                [p['name'].replace('-', '_')],
+                type=param_type,
+                required=True,
+            )
+        )
+
+    # Query parameters -> --option flags
+    for p in endpoint['query_params']:
+        param_type = _CLICK_TYPE_MAP.get(p.get('schema', {}).get('type', 'string'), click.STRING)
+        option_name = _param_to_option_name(p['name'])
+        required = p.get('required', False)
+        default = p.get('schema', {}).get('default')
+
+        schema = p.get('schema', {})
+        if 'enum' in schema:
+            param_type = click.Choice(schema['enum'])
+
+        params.append(
+            click.Option(
+                [option_name],
+                type=param_type,
+                required=required,
+                default=default,
+                help=p.get('description', ''),
+                show_default=default is not None,
+            )
+        )
+
+    return params
+
+
+def _build_endpoint_command(cmd_name: str, endpoint: dict) -> click.Command:
+    """Build a Click command for an API endpoint.
+
+    Path parameters become required CLI arguments.
+    Query parameters become --option flags with proper types.
+    """
+    ep_path = endpoint['path']
+    ep_method = endpoint['method']
+    ep_path_params = list(endpoint['path_params'])
+    ep_query_params = list(endpoint['query_params'])
+    ep_description = endpoint['description'] or endpoint['summary']
+
+    # Build a mapping from Click's normalized kwarg name to original OpenAPI param name
+    _path_param_map = {p['name'].replace('-', '_').lower(): p['name'] for p in ep_path_params}
+    _query_param_map = {re.sub(r'[^a-z0-9]+', '_', p['name'].lower()).strip('_'): p['name'] for p in ep_query_params}
+
+    def _callback(**kwargs: Any) -> None:
+        ctx = click.get_current_context()
+
+        # Extract path param values using the mapping
+        path_values = {}
+        for kwarg_key, original_name in _path_param_map.items():
+            if kwarg_key in kwargs and kwargs[kwarg_key] is not None:
+                path_values[original_name] = kwargs[kwarg_key]
+
+        # Extract query param values (skip None)
+        query_values = {}
+        for kwarg_key, original_name in _query_param_map.items():
+            value = kwargs.get(kwarg_key)
+            if value is not None:
+                query_values[original_name] = value
+
+        # Get auth from root context (set by app_callback)
+        root_ctx = ctx.find_root()
+        client_id = root_ctx.obj.get('client_id') if root_ctx.obj else None
+        client_secret = root_ctx.obj.get('client_secret') if root_ctx.obj else None
+
+        try:
+            result = _make_api_request(
+                ep_path,
+                ep_method,
+                path_values,
+                query_values,
+                client_id=client_id,
+                client_secret=client_secret,
+            )
+        except Exception as e:
+            click.echo(f'Error: {e}', err=True)
+            raise click.Abort from e
+
+        click.echo(json.dumps(result, indent=2))
+
+    return click.Command(
+        name=cmd_name,
+        callback=_callback,
+        help=ep_description,
+        short_help=endpoint['summary'],
+        params=_build_click_params(endpoint),
+    )