feat(components): Support for querying Development status for a component. (SP4197)

Author: scanoss-qg

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+
+## [1.52.0] - 2026-04-06
+### Added
+- Added `status` subcommand query to `component` command to retrieve development life-cycle staus:
+  - Component and version specific for a single component
+  - Component and version specific for a list of components
+
 ## [1.51.1] - 2026-04-01
 ### Fixed
 - Fixed vulnerabilities not appearing in CycloneDX output for folder-scan (`fs`) command
@@ -869,3 +876,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [1.50.1]: https://github.com/scanoss/scanoss.py/compare/v1.50.0...v1.50.1
 [1.51.0]: https://github.com/scanoss/scanoss.py/compare/v1.50.1...v1.51.0
 [1.51.1]: https://github.com/scanoss/scanoss.py/compare/v1.51.0...v1.51.1
+[1.52.0]: https://github.com/scanoss/scanoss.py/compare/v1.51.1...v1.52.0

CLIENT_HELP.md

@@ -423,6 +423,8 @@ The `component` command has a suite of sub-commands designed to operate on OSS c
 * Version Details (`versions`)
 * Cryptography (`crypto`)
 * Provenance (`provenance`)
+* Licenses (`licenses`)
+* Status (`status`)
 
 For the latest list of sub-commands, please run:
 ```bash
@@ -518,14 +520,38 @@ The licenses command also supports CycloneDX (CDX) input files. You can provide
 scanoss-py comp licenses -i cyclonedx-sbom.json -o component-licenses.json
 ```
 
+#### Component Status
+The following command provides the capability to search the SCANOSS KB for development status information of Open Source components:
+```bash
+scanoss-py comp status -p "pkg:npm/react@17.0.2"
+```
+It is possible to supply multiple PURLs by repeating the `-p pkg` option, or providing a purl input file `-i purl-input.json` ([for example](tests/data/purl-input.json)):
+```bash
+scanoss-py comp status -i purl-input.json -o component-status.json
+```
+
+The status command also supports CycloneDX (CDX) input files. You can provide a CycloneDX SBOM file and retrieve status information for all components:
+```bash
+scanoss-py comp status -i cyclonedx-sbom.json -o component-status.json
+```
+
+The component status provides information about:
+- **Component status**: Overall status of the component (active, inactive, deprecated)
+- **Repository status**: Current status of the component's repository
+- **First indexed date**: When the component was first indexed in SCANOSS KB
+- **Last indexed date**: Most recent indexing date
+- **Version status**: Status specific to the requested version
+- **Indexed date**: When the specific version was indexed
+
 ### CDX Input Support for Component Commands
 Several component commands now support CycloneDX (CDX) input files. This allows you to analyze components from existing SBOM files:
 
 **Supported commands with CDX input:**
 - `comp vulns` - Analyze vulnerabilities from CDX file
-- `comp licenses` - Retrieve licenses from CDX file  
+- `comp licenses` - Retrieve licenses from CDX file
 - `comp crypto` - Detect cryptographic algorithms from CDX file
 - `comp semgrep` - Find semgrep issues from CDX file
+- `comp status` - Retrieve development status from CDX file
 
 **Example using CDX input:**
 ```bash
@@ -535,6 +561,9 @@ scanoss-py comp vulns -i sbom.cdx.json -o vulnerabilities.json
 # Get licenses for all components in a CycloneDX SBOM
 scanoss-py comp licenses -i sbom.cdx.json -o licenses.json
 
+# Get status information for all components in a CycloneDX SBOM
+scanoss-py comp status -i sbom.cdx.json -o status.json
+
 # Detect cryptographic usage from CDX
 scanoss-py comp crypto -i sbom.cdx.json -o crypto-findings.json
 ```

src/scanoss/cli.py

@@ -420,6 +420,15 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
     c_versions.add_argument('--limit', '-l', type=int, help='Generic component search')
     c_versions.set_defaults(func=comp_versions)
 
+    # Component Sub-command: component status
+    c_status = comp_sub.add_parser(
+        'status',
+        aliases=['stat'],
+        description=f'Show Component Status details: {__version__}',
+        help='Retrieve development status for the given components',
+    )
+    c_status.set_defaults(func=comp_status)
+
     # Sub-command: crypto
     p_crypto = subparsers.add_parser(
         'crypto',
@@ -478,6 +487,7 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         p_crypto_hints,
         p_crypto_versions_in_range,
         c_licenses,
+        c_status,
     ]:
         p.add_argument('--purl', '-p', type=str, nargs='*', help='Package URL - PURL to process.')
         p.add_argument('--input', '-i', type=str, help='Input file name')
@@ -493,6 +503,7 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         p_crypto_hints,
         p_crypto_versions_in_range,
         c_licenses,
+        c_status,
     ]:
         p.add_argument(
             '--timeout',
@@ -510,6 +521,7 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         c_semgrep,
         c_provenance,
         c_licenses,
+        c_status,
     ]:
         p.add_argument(
             '--apiurl', type=str, help='SCANOSS API base URL (optional - default: https://api.osskb.org)'
@@ -1090,6 +1102,7 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         p_crypto_hints,
         p_crypto_versions_in_range,
         c_licenses,
+        c_status,
         p_copy,
     ]:
         p.add_argument('--output', '-o', type=str, help='Output result file name (optional - default stdout).')
@@ -1178,6 +1191,7 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         p_crypto_hints,
         p_crypto_versions_in_range,
         c_licenses,
+        c_status,
     ]:
         p.add_argument(
             '--key', '-k', type=str, help='SCANOSS API Key token (optional - not required for default OSSKB URL)'
@@ -1215,6 +1229,7 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         p_crypto_hints,
         p_crypto_versions_in_range,
         c_licenses,
+        c_status,
     ]:
         p.add_argument(
             '--api2url', type=str,
@@ -1261,6 +1276,7 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         c_search,
         c_versions,
         c_licenses,
+        c_status,
         p_folder_scan,
     ]:
         p.add_argument(
@@ -1305,6 +1321,7 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         p_crypto_hints,
         p_crypto_versions_in_range,
         c_licenses,
+        c_status,
         e_dt,
         p_copy,
     ]:
@@ -2652,6 +2669,41 @@ def comp_licenses(parser, args):
         sys.exit(1)
 
 
+def comp_status(parser, args):
+    """
+    Run the "component status" sub-command
+    Parameters
+    ----------
+        parser: ArgumentParser
+            command line parser object
+        args: Namespace
+            Parsed arguments
+    """
+    if (not args.purl and not args.input) or (args.purl and args.input):
+        print_stderr('ERROR: Please specify an input file or purl to decorate (--purl or --input)')
+        parser.parse_args([args.subparser, args.subparsercmd, '-h'])
+        sys.exit(1)
+    if args.ca_cert and not os.path.exists(args.ca_cert):
+        print_stderr(f'ERROR: Certificate file does not exist: {args.ca_cert}.')
+        sys.exit(1)
+    pac_file = get_pac_file(args.pac)
+    comps = Components(
+        debug=args.debug,
+        trace=args.trace,
+        quiet=args.quiet,
+        grpc_url=args.apiurl,  # Legacy param name; accepts the REST API base URL. TODO: rename to url
+        api_key=args.key,
+        ca_cert=args.ca_cert,
+        proxy=args.proxy,
+        pac=pac_file,
+        timeout=args.timeout,
+        req_headers=process_req_headers(args.header),
+        ignore_cert_errors=args.ignore_cert_errors,
+    )
+    if not comps.get_status(args.input, args.purl, args.output):
+        sys.exit(1)
+
+
 def results(parser, args):
     """
     Run the "results" sub-command

src/scanoss/components.py

@@ -395,3 +395,36 @@ def get_licenses(self, json_file: str = None, purls: [] = None, output_file: str
                 self.print_msg(f'Results written to: {output_file}')
         self._close_file(output_file, file)
         return success
+
+    def get_status(self, json_file: str = None, purls: [] = None, output_file: str = None) -> bool:
+        """
+        Retrieve the development status details for the supplied PURLs
+
+        Args:
+            json_file (str, optional): Input JSON file. Defaults to None.
+            purls (None, optional): PURLs to retrieve status details for. Defaults to None.
+            output_file (str, optional): Output file. Defaults to None.
+
+        Returns:
+            bool: True on success, False otherwise
+        """
+        success = False
+
+        purls_request = self.load_purls(json_file, purls)
+        if not purls_request:
+            return False
+        file = self._open_file_or_sdtout(output_file)
+        if file is None:
+            return False
+
+        # Use ComponentBatchRequest format for the status api
+        component_batch_request = {'components': purls_request.get('purls')}
+        self.print_msg('Sending PURLs to Component Status API...')
+        response = self.grpc_api.get_component_status(component_batch_request, use_grpc=self.use_grpc)
+        if response:
+            print(json.dumps(response, indent=2, sort_keys=True), file=file)
+            success = True
+            if output_file:
+                self.print_msg(f'Results written to: {output_file}')
+        self._close_file(output_file, file)
+        return success

src/scanoss/scanossgrpc.py

@@ -95,6 +95,7 @@
     },
     'components.SearchComponents': {'path': '/components/search', 'method': 'GET'},
     'components.GetComponentVersions': {'path': '/components/versions', 'method': 'GET'},
+    'components.GetComponentsStatus': {'path': '/components/status/components', 'method': 'POST'},
     'geoprovenance.GetCountryContributorsByComponents': {
         'path': '/geoprovenance/countries/components',
         'method': 'POST',
@@ -765,6 +766,29 @@ def get_licenses(self, request: Dict, use_grpc: Optional[bool] = None) -> Option
             use_grpc=use_grpc,
         )
 
+    def get_component_status(self, request: Dict, use_grpc: Optional[bool] = None) -> Optional[Dict]:
+        """
+        Client function to call the API for Components GetComponentsStatus
+        Only REST API is supported for this endpoint (gRPC not yet available)
+
+        Args:
+            request (Dict): ComponentsRequest
+        Returns:
+            Optional[Dict]: ComponentsStatusResponse, or None if the request was not successful
+        """
+        # Force REST API since gRPC is not available for this endpoint
+        if use_grpc:
+            self.print_stderr('WARNING: gRPC is not supported for component status. Using REST API instead.')
+
+        return self._call_api(
+            'components.GetComponentsStatus',
+            None,  # No gRPC method available
+            request,
+            ComponentsRequest,
+            'Sending data for component status retrieval (rqId: {rqId})...',
+            use_grpc=False,  # Force REST
+        )
+
     def load_generic_headers(self, url: Optional[str] = None):
         """
         Adds custom headers from req_headers to metadata.