feat: add --enable-diff flag and improve license policy violation handling

- Add --enable-diff flag to force differential scanning even when using --integration api
- Improve license policy violation grouping and display in PR comments
- Fix alert consolidation logic to prevent duplicate alerts based on manifest files
- Enhance empty baseline scan creation with proper file cleanup
- Add comprehensive test coverage for new enable_diff functionality
- Update documentation with new scanning mode examples and usage patterns

The --enable-diff flag enables differential mode without SCM integration,
useful for getting diff reports while using the API integration type.
License policy violations are now properly grouped by package and displayed
with consistent formatting in GitHub PR comments.

Author: dacoburn

README.md

@@ -116,6 +116,7 @@ If you don't want to provide the Socket API Token every time then you can use th
 |:-------------------------|:---------|:--------|:----------------------------------------------------------------------|
 | --ignore-commit-files    | False    | False   | Ignore commit files                                                   |
 | --disable-blocking       | False    | False   | Disable blocking mode                                                 |
+| --enable-diff            | False    | False   | Enable diff mode even when using --integration api (forces diff mode without SCM integration) |
 | --scm                    | False    | api     | Source control management type                                        |
 | --timeout                | False    |         | Timeout in seconds for API requests                                   |
 | --include-module-folders | False    | False   | If enabled will include manifest files from folders like node_modules |
@@ -205,13 +206,15 @@ The CLI determines which files to scan based on the following logic:
 - **Differential Mode**: When manifest files are detected in changes, performs a diff scan with PR/MR comment integration
 - **API Mode**: When no manifest files are in changes, creates a full scan report without PR comments but still scans the entire repository
 - **Force Mode**: With `--ignore-commit-files`, always performs a full scan regardless of changes
+- **Forced Diff Mode**: With `--enable-diff`, forces differential mode even when using `--integration api` (without SCM integration)
 
 ### Examples
 
 - **Commit with manifest file**: If your commit includes changes to `package.json`, a differential scan will be triggered automatically with PR comment integration.
 - **Commit without manifest files**: If your commit only changes non-manifest files (like `.github/workflows/socket.yaml`), the CLI automatically switches to API mode and performs a full repository scan.
 - **Using `--files`**: If you specify `--files '["package.json"]'`, the CLI will check if this file exists and is a manifest file before determining scan type.
 - **Using `--ignore-commit-files`**: This forces a full scan of all manifest files in the target path, regardless of what's in your commit.
+- **Using `--enable-diff`**: Forces diff mode without SCM integration - useful when you want differential scanning but are using `--integration api`. For example: `socketcli --integration api --enable-diff --target-path /path/to/repo`
 - **Auto-detection**: Most CI/CD scenarios now work with just `socketcli --target-path /path/to/repo --scm github --pr-number $PR_NUM`
 
 ## Debugging and Troubleshooting

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "socketsecurity"
-version = "2.1.36"
+version = "2.1.37"
 requires-python = ">= 3.10"
 license = {"file" = "LICENSE"}
 dependencies = [

socketsecurity/__init__.py

@@ -1,2 +1,2 @@
 __author__ = 'socket.dev'
-__version__ = '2.1.36'
+__version__ = '2.1.37'

socketsecurity/config.py

@@ -48,6 +48,7 @@ class CliConfig:
     integration_type: IntegrationType = "api"
     integration_org_slug: Optional[str] = None
     pending_head: bool = False
+    enable_diff: bool = False
     timeout: Optional[int] = 1200
     exclude_license_details: bool = False
     include_module_folders: bool = False
@@ -421,6 +422,12 @@ def create_argument_parser() -> argparse.ArgumentParser:
         action="store_true",
         help=argparse.SUPPRESS
     )
+    advanced_group.add_argument(
+        "--enable-diff",
+        dest="enable_diff",
+        action="store_true",
+        help="Enable diff mode even when using --integration api (forces diff mode without SCM integration)"
+    )
     advanced_group.add_argument(
         "--scm",
         metavar="<type>",

socketsecurity/core/__init__.py

@@ -2,6 +2,7 @@
 import os
 import sys
 import tarfile
+import tempfile
 import time
 import io
 import json
@@ -433,12 +434,22 @@ def to_case_insensitive_regex(input_string: str) -> str:
         return ''.join(f'[{char.lower()}{char.upper()}]' if char.isalpha() else char for char in input_string)
 
     @staticmethod
-    def empty_head_scan_file() -> list[tuple[str, tuple[str, Union[BinaryIO, BytesIO]]]]:
-        # Create an empty file for when no head full scan so that the diff endpoint can always be used
-        empty_file_obj = io.BytesIO(b"")
-        empty_filename = "initial_head_scan"
-        empty_full_scan_file = [(empty_filename, (empty_filename, empty_file_obj))]
-        return empty_full_scan_file
+    def empty_head_scan_file() -> List[str]:
+        """
+        Creates a temporary empty file for baseline scans when no head scan exists.
+        
+        Returns:
+            List containing path to a temporary empty file
+        """
+        # Create a temporary empty file
+        temp_fd, temp_path = tempfile.mkstemp(suffix='.empty', prefix='socket_baseline_')
+        
+        # Close the file descriptor since we just need the path
+        # The file is already created and empty
+        os.close(temp_fd)
+        
+        log.debug(f"Created temporary empty file for baseline scan: {temp_path}")
+        return [temp_path]
 
     def create_full_scan(self, files: List[str], params: FullScanParams) -> FullScan:
         """
@@ -874,16 +885,39 @@ def create_new_diff(
         except APIResourceNotFound:
             head_full_scan_id = None
 
+        # If no head scan exists, create an empty baseline scan
         if head_full_scan_id is None:
+            log.info("No previous scan found - creating empty baseline scan")
             new_params = copy.deepcopy(params.__dict__)
             new_params.pop('include_license_details')
             tmp_params = FullScanParams(**new_params)
             tmp_params.include_license_details = params.include_license_details
             tmp_params.tmp = True
             tmp_params.set_as_pending_head = False
             tmp_params.make_default_branch = False
-            head_full_scan = self.create_full_scan(Core.empty_head_scan_file(), tmp_params)
-            head_full_scan_id = head_full_scan.id
+            
+            # Create baseline scan with empty file
+            empty_files = Core.empty_head_scan_file()
+            try:
+                head_full_scan = self.create_full_scan(empty_files, tmp_params)
+                head_full_scan_id = head_full_scan.id
+                log.debug(f"Created empty baseline scan: {head_full_scan_id}")
+                
+                # Clean up the temporary empty file
+                for temp_file in empty_files:
+                    try:
+                        os.unlink(temp_file)
+                        log.debug(f"Cleaned up temporary file: {temp_file}")
+                    except OSError as e:
+                        log.warning(f"Failed to clean up temporary file {temp_file}: {e}")
+            except Exception as e:
+                # Clean up temp files even if scan creation fails
+                for temp_file in empty_files:
+                    try:
+                        os.unlink(temp_file)
+                    except OSError:
+                        pass
+                raise e
 
         # Create new scan
         try:
@@ -900,6 +934,7 @@ def create_new_diff(
             log.error(f"Stack trace:\n{traceback.format_exc()}")
             raise
 
+        # Handle diff generation - now we always have both scans
         scans_ready = self.check_full_scans_status(head_full_scan_id, new_full_scan.id)
         if scans_ready is False:
             log.error(f"Full scans did not complete within {self.config.timeout} seconds")
@@ -1121,6 +1156,12 @@ def add_package_alerts_to_collection(self, package: Package, alerts_collection:
             alert = Alert(**alert_item)
             props = getattr(self.config.all_issues, alert.type, default_props)
             introduced_by = self.get_source_data(package, packages)
+            
+            # Handle special case for license policy violations
+            title = props.title
+            if alert.type == "licenseSpdxDisj" and not title:
+                title = "License Policy Violation"
+            
             issue_alert = Issue(
                 pkg_type=package.type,
                 pkg_name=package.name,
@@ -1131,7 +1172,7 @@ def add_package_alerts_to_collection(self, package: Package, alerts_collection:
                 type=alert.type,
                 severity=alert.severity,
                 description=props.description,
-                title=props.title,
+                title=title,
                 suggestion=props.suggestion,
                 next_step_title=props.nextStepTitle,
                 introduced_by=introduced_by,
@@ -1218,7 +1259,8 @@ def get_new_alerts(
             if alert_key not in removed_package_alerts:
                 new_alerts = added_package_alerts[alert_key]
                 for alert in new_alerts:
-                    alert_str = f"{alert.purl},{alert.manifests},{alert.type}"
+                    # Consolidate by package and alert type, not by manifest details
+                    alert_str = f"{alert.purl},{alert.type}"
 
                     if alert.error or alert.warn:
                         if alert_str not in consolidated_alerts:
@@ -1229,7 +1271,8 @@ def get_new_alerts(
                 removed_alerts = removed_package_alerts[alert_key]
 
                 for alert in new_alerts:
-                    alert_str = f"{alert.purl},{alert.manifests},{alert.type}"
+                    # Consolidate by package and alert type, not by manifest details
+                    alert_str = f"{alert.purl},{alert.type}"
 
                     # Only add if:
                     # 1. Alert isn't in removed packages (or we're not ignoring readded alerts)

socketsecurity/core/messages.py

@@ -309,13 +309,26 @@ def security_comment_template(diff: Diff) -> str:
         :param diff: Diff - Contains the detected vulnerabilities and warnings.
         :return: str - The formatted Markdown/HTML string.
         """
+        # Group license policy violations by PURL (ecosystem/package@version)
+        license_groups = {}
+        security_alerts = []
+        
+        for alert in diff.new_alerts:
+            if alert.type == "licenseSpdxDisj":
+                purl_key = f"{alert.pkg_type}/{alert.pkg_name}@{alert.pkg_version}"
+                if purl_key not in license_groups:
+                    license_groups[purl_key] = []
+                license_groups[purl_key].append(alert)
+            else:
+                security_alerts.append(alert)
+
         # Start of the comment
         comment = """<!-- socket-security-comment-actions -->
 
 > **❗️ Caution**  
 > **Review the following alerts detected in dependencies.**  
 >  
-> According to your organization’s Security Policy, you **must** resolve all **“Block”** alerts before proceeding. It’s recommended to resolve **“Warn”** alerts too.  
+> According to your organization's Security Policy, you **must** resolve all **"Block"** alerts before proceeding. It's recommended to resolve **"Warn"** alerts too.  
 > Learn more about [Socket for GitHub](https://socket.dev?utm_medium=gh).
 
 <!-- start-socket-updated-alerts-table -->
@@ -330,8 +343,8 @@ def security_comment_template(diff: Diff) -> str:
   <tbody>
     """
 
-        # Loop through alerts, dynamically generating rows
-        for alert in diff.new_alerts:
+        # Loop through security alerts (non-license), dynamically generating rows
+        for alert in security_alerts:
             severity_icon = Messages.get_severity_icon(alert.severity)
             action = "Block" if alert.error else "Warn"
             details_open = ""
@@ -365,7 +378,48 @@ def security_comment_template(diff: Diff) -> str:
 <!-- end-socket-alert-{alert.pkg_name}@{alert.pkg_version} -->
     """
 
-        # Close table and comment
+        # Add license policy violation entries grouped by PURL
+        for purl_key, alerts in license_groups.items():
+            action = "Block" if any(alert.error for alert in alerts) else "Warn"
+            first_alert = alerts[0]
+            
+            # Use orange diamond for license policy violations
+            license_icon = "🔶"
+            
+            # Build license findings list
+            license_findings = []
+            for alert in alerts:
+                license_findings.append(alert.title)
+            
+            comment += f"""
+<!-- start-socket-alert-{first_alert.pkg_name}@{first_alert.pkg_version} -->
+<tr>
+  <td><strong>{action}</strong></td>
+  <td align="center">{license_icon}</td>
+  <td>
+    <details>
+      <summary>{first_alert.pkg_name}@{first_alert.pkg_version} has a License Policy Violation.</summary>
+      <p><strong>License findings:</strong></p>
+      <ul>
+"""
+            for finding in license_findings:
+                comment += f"        <li>{finding}</li>\n"
+            
+            comment += f"""      </ul>
+      <p><strong>From:</strong> {first_alert.manifests}</p>
+      <p>ℹ️ Read more on: <a href="{first_alert.purl}">This package</a> | <a href="https://socket.dev/alerts/license">What is a license policy violation?</a></p>
+      <blockquote>
+        <p><em>Next steps:</em> Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at <strong>support@socket.dev</strong>.</p>
+        <p><em>Suggestion:</em> Find a package that does not violate your license policy or adjust your policy to allow this package's license.</p>
+        <p><em>Mark the package as acceptable risk:</em> To ignore this alert only in this pull request, reply with the comment <code>@SocketSecurity ignore {first_alert.pkg_name}@{first_alert.pkg_version}</code>. You can also ignore all packages with <code>@SocketSecurity ignore-all</code>. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.</p>
+      </blockquote>
+    </details>
+  </td>
+</tr>
+<!-- end-socket-alert-{first_alert.pkg_name}@{first_alert.pkg_version} -->
+    """
+
+        # Close table
         comment += """
   </tbody>
 </table>

socketsecurity/socketcli.py

@@ -320,6 +320,33 @@ def main_code():
             diff = core.create_new_diff(config.target_path, params, no_change=should_skip_scan, save_files_list_path=config.save_submitted_files_list, save_manifest_tar_path=config.save_manifest_tar)
 
         output_handler.handle_output(diff)
+    
+    elif config.enable_diff and not force_api_mode:
+        # New logic: --enable-diff forces diff mode even with --integration api (no SCM)
+        log.info("Diff mode enabled without SCM integration")
+        diff = core.create_new_diff(config.target_path, params, no_change=should_skip_scan, save_files_list_path=config.save_submitted_files_list, save_manifest_tar_path=config.save_manifest_tar)
+        output_handler.handle_output(diff)
+    
+    elif config.enable_diff and force_api_mode:
+        # User requested diff mode but no manifest files were detected
+        log.warning("--enable-diff was specified but no supported manifest files were detected in the changed files. Falling back to full scan mode.")
+        log.info("Creating Socket Report (full scan)")
+        serializable_params = {
+            key: value if isinstance(value, (int, float, str, list, dict, bool, type(None))) else str(value)
+            for key, value in params.__dict__.items()
+        }
+        log.debug(f"params={serializable_params}")
+        diff = core.create_full_scan_with_report_url(
+            config.target_path,
+            params,
+            no_change=should_skip_scan,
+            save_files_list_path=config.save_submitted_files_list,
+            save_manifest_tar_path=config.save_manifest_tar
+        )
+        log.info(f"Full scan created with ID: {diff.id}")
+        log.info(f"Full scan report URL: {diff.report_url}")
+        output_handler.handle_output(diff)
+    
     else:
         if force_api_mode:
             log.info("No Manifest files changed, creating Socket Report")

tests/unit/test_cli_config.py

@@ -24,8 +24,20 @@ def test_default_values(self):
     @pytest.mark.parametrize("flag,attr", [
         ("--enable-debug", "enable_debug"),
         ("--disable-blocking", "disable_blocking"),
-        ("--allow-unverified", "allow_unverified")
+        ("--allow-unverified", "allow_unverified"),
+        ("--enable-diff", "enable_diff")
     ])
     def test_boolean_flags(self, flag, attr):
         config = CliConfig.from_args(["--api-token", "test", flag])
-        assert getattr(config, attr) is True
+        assert getattr(config, attr) is True
+
+    def test_enable_diff_default_false(self):
+        """Test that enable_diff defaults to False"""
+        config = CliConfig.from_args(["--api-token", "test"])
+        assert config.enable_diff is False
+
+    def test_enable_diff_with_integration_api(self):
+        """Test that enable_diff can be used with integration api"""
+        config = CliConfig.from_args(["--api-token", "test", "--integration", "api", "--enable-diff"])
+        assert config.enable_diff is True
+        assert config.integration_type == "api"