regscale-cli 6.16.0.0__py3-none-any.whl

regscale/models/regscale_models/threat.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Dataclass for a RegScale Threat"""
+
+# standard python imports
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any, List, Optional, Union
+
+from pydantic import ConfigDict, Field
+
+from regscale.core.app.api import Api
+from regscale.core.app.utils.app_utils import get_current_datetime
+from regscale.models.regscale_models.regscale_model import RegScaleModel
+
+
+class Threat(RegScaleModel):
+    """Threat Model"""
+
+    _module_slug = "threats"
+    _exclude_graphql_fields = ["tenantsId"]
+
+    threatType: str  # Required
+    status: Optional[str] = "Under Investigation"  # Required
+    source: Optional[str] = "Open Source"  # Required
+    title: Optional[str] = ""  # Required
+    targetType: Optional[str] = ""  # Required
+    threatOwnerId: Optional[str] = Field(default_factory=RegScaleModel.get_user_id)  # Required
+    id: Optional[int] = 0
+    uuid: Optional[str] = None
+    investigationResults: Optional[str] = ""
+    notes: Optional[str] = ""
+    dateIdentified: str = Field(default_factory=get_current_datetime)
+    dateResolved: Optional[str] = ""
+    dateCreated: str = Field(default_factory=get_current_datetime)
+    description: Optional[str] = ""
+    targets: Optional[str] = ""
+    vulnerabilityAnalysis: Optional[str] = ""
+    mitigations: Optional[str] = ""
+    threatTypeUnintentional: Optional[bool] = True
+    threatTypePurposeful: Optional[bool] = True
+    threatTypeEnvironmental: Optional[bool] = True
+    threatTypeInsider: Optional[bool] = True
+    threatImpactConfidentiality: Optional[bool] = True
+    threatImpactIntegrity: Optional[bool] = True
+    threatImpactAvailability: Optional[bool] = True
+    investigated: Optional[bool] = True
+    exploitable: Optional[bool] = True
+    isPublic: Optional[bool] = True
+    facilityId: Optional[int] = None  # This has to be None for default or else the server returns a 500 error
+    orgId: Optional[int] = None  # This has to be None for default or else the server returns a 500 error
+    parentModule: Optional[str] = ""
+    parentId: Optional[int] = 0
+    tenantsId: Optional[int] = 1
+
+    @staticmethod
+    def _get_additional_endpoints() -> ConfigDict:
+        """
+        Get additional endpoints for the Issues model.
+
+        :return: A dictionary of additional endpoints
+        :rtype: ConfigDict
+        """
+        return ConfigDict(
+            get_count="/api/{model_slug}/count",
+            get_all_by_parent="/api/{model_slug}/getAllByParent/{intParentId}/{strModule}",
+            get_filtered_list="/api/{model_slug}/getFilteredList/{strFind}",
+            get_all_by_parent_module="/api/{model_slug}/getAllByParentModule/{strModule}",
+            graph="/api/{model_slug}/graph",
+            graph_by_date="/api/{model_slug}/graphByDate/{strGroupBy}/{year}",
+            filter_threats="/api/{model_slug}/filterThreats",
+            query_by_custom_field="/api/{model_slug}/queryByCustomField/{strFieldName}/{strValue}",
+            report="/api/{model_slug}/report/{strReport}",
+            schedule="/api/{model_slug}/schedule/{year}/{dvar}",
+            main_dashboard="/api/{model_slug}/mainDashboard/{intYear}",
+            main_dashboard_chart="/api/{model_slug}/mainDashboardChart/{year}",
+            dashboard="/api/{model_slug}/dashboard/{strGroupBy}",
+            dashboard_by_parent="/api/{model_slug}/dashboardByParent/{strGroupBy}/{intId}/{strModule}",
+        )
+
+    @staticmethod
+    def xstr(str_eval: Any) -> str:
+        """
+        Replaces string with None value to ""
+
+        :param Any str_eval: key to replace None value to ""
+        :return: Updates provided str field to ""
+        :rtype: str
+        """
+        return "" if str_eval is None else str_eval
+
+    @staticmethod
+    def bulk_insert(api: Optional[Api], threats: list[Union[dict, "Threat"]]) -> List["Threat"]:
+        """
+        Bulk insert Threats to the RegScale API
+
+        :param Optional[Api] api: RegScale API
+        :param list[Union[dict, Threat]] threats: List of Threats to insert
+        :return: List of Threat objects from RegScale API
+        :rtype: List[Threat]
+        """
+        if api:
+            import warnings
+
+            warnings.warn(
+                "Api parameter is deprecated and will be removed in future versions.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        results = []
+        threat_objects = []
+        for threat in threats:
+            if isinstance(threat, dict):
+                threat_objects.append(Threat(**threat))
+            else:
+                threat_objects.append(threat)
+
+        with ThreadPoolExecutor(max_workers=30) as executor:
+            futures = [
+                executor.submit(
+                    threat.create,
+                )
+                for threat in threat_objects
+            ]
+            for future in as_completed(futures):
+                results.append(future.result())
+        return results
+
+    @staticmethod
+    def bulk_update(api: Optional[Api], threats: list[Union[dict, "Threat"]]) -> List["Threat"]:
+        """
+        Bulk insert Threats to the RegScale API
+
+        :param Optional[Api] api: RegScale API
+        :param list[Union[dict, Threat]] threats: List of Threats to update
+        :return: List of Threat objects from RegScale API
+        :rtype: List[Threat]
+        """
+        if api:
+            import warnings
+
+            warnings.warn(
+                "Api parameter is deprecated and will be removed in future versions.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        results = []
+        threat_objects = []
+        for threat in threats:
+            if isinstance(threat, dict):
+                threat_objects.append(Threat(**threat))
+            else:
+                threat_objects.append(threat)
+
+        # use threadpoolexecutor to speed up inserts
+        with ThreadPoolExecutor(max_workers=30) as executor:
+            futures = [
+                executor.submit(
+                    threat.save,
+                )
+                for threat in threat_objects
+            ]
+            for future in as_completed(futures):
+                results.append(future.result())
+        return results
+
+    @staticmethod
+    def fetch_all_threats() -> List["Threat"]:
+        """
+        Find all Threats in RegScale
+
+        :return: List of Threats from RegScale
+        :rtype: List[Threat]
+        """
+        from json import JSONDecodeError
+
+        api = Api()
+        body = f"""
+            query {{
+                threats(take: 50, skip: 0) {{
+                items {{
+                    {Threat.build_graphql_fields()}
+                }}
+                pageInfo {{
+                    hasNextPage
+                }}
+                ,totalCount}}
+            }}
+            """
+        try:
+            api.logger.info("Retrieving all threats from RegScale...")
+            existing_threats = api.graph(query=body)["threats"]["items"]
+            api.logger.info("Retrieved %i threat(s) from RegScale.", len(existing_threats))
+        except (JSONDecodeError, KeyError):
+            existing_threats = []
+        return [Threat(**threat) for threat in existing_threats]

regscale/models/regscale_models/user.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Dataclass for a RegScale User"""
+
+# standard python imports
+import random
+import string
+from typing import cast, Optional, List
+
+from pydantic import Field, ConfigDict, field_validator
+
+from regscale.core.app.utils.app_utils import get_current_datetime
+from .regscale_model import RegScaleModel, T
+
+
+def generate_password() -> str:
+    """
+    Generates a random string that is 12-20 characters long
+
+    :return: random string 12-20 characters long
+    :rtype: str
+    """
+    # select a random password length between 12-20 characters
+    length = random.randint(12, 20)
+
+    # get all possible strings to create a password
+    all_string_chars = string.ascii_lowercase + string.ascii_uppercase + string.digits + string.punctuation
+
+    # randomly select characters matching the random length
+    temp = random.sample(all_string_chars, length)
+    # return a string from the temp list of samples
+    return "".join(temp)
+
+
+class User(RegScaleModel):
+    """User Model"""
+
+    model_config = ConfigDict(populate_by_name=True)
+    _module_slug = "accounts"
+    _unique_fields = [
+        ["userName", "email"],
+    ]
+    _exclude_graphql_fields = ["extra_data", "tenantsId", "password"]
+
+    userName: str = Field(alias="username")
+    email: Optional[str] = None
+    firstName: Optional[str] = None
+    lastName: Optional[str] = None
+    tenantId: int = 1
+    initials: Optional[str] = None
+    id: Optional[str] = None
+    password: str = Field(default_factory=generate_password)
+    homePageUrl: Optional[str] = "/workbench"
+    name: Optional[str] = None
+    workPhone: Optional[str] = None
+    mobilePhone: Optional[str] = None
+    avatar: Optional[bytes] = None
+    jobTitle: Optional[str] = None
+    orgId: Optional[int] = None
+    pictureURL: Optional[str] = None
+    activated: bool = False
+    emailNotifications: bool = True
+    ldapUser: bool = False
+    externalId: Optional[str] = None
+    dateCreated: Optional[str] = Field(default_factory=get_current_datetime)
+    lastLogin: Optional[str] = None
+    readOnly: bool = True
+    roles: Optional[List[str]] = None
+
+    @field_validator("homePageUrl")
+    def validate_regscale_version_and_home_page_url(cls, v: str) -> Optional[str]:
+        """
+        Validate the RegScale version and if it is compatible with homePageUrl, has to be >=6.13
+
+        :param str v: homePageUrl value
+        :return: The homePageUrl if the RegScale version is compatible, None otherwise
+        """
+        from packaging.version import Version
+
+        regscale_version = cls._get_api_handler().regscale_version
+
+        if len(regscale_version) >= 10 or Version(regscale_version) >= Version("6.14.0.0"):
+            return v
+        else:
+            return None
+
+    @classmethod
+    def _get_additional_endpoints(cls) -> ConfigDict:
+        """
+        Get additional endpoints for the Accounts model, using {model_slug} as a placeholder for the model slug.
+
+        :return: A dictionary of additional endpoints
+        :rtype: ConfigDict
+        """
+        return ConfigDict(
+            get_all="/api/{model_slug}",
+            create_account=cls._module_slug_url,
+            update_account=cls._module_slug_url,
+            get_accounts=cls._module_slug_url,
+            register_questionnaire_user="/api/{model_slug}/registerQuestionnaireUser",
+            cache_reset="/api/{model_slug}/cacheReset",
+            create_ldap_accounts="/api/{model_slug}/ldap",
+            create_azuread_accounts="/api/{model_slug}/azureAD",
+            assign_role="/api/{model_slug}/assignRole",
+            check_role="/api/{model_slug}/checkRole/{strUserId}/{strRoleId}",
+            delete_role="/api/{model_slug}/deleteRole/{strUserId}/{strRoleId}",
+            get_my_manager="/api/{model_slug}/getMyManager",
+            get_manager_by_user_id="/api/{model_slug}/getManagerByUserId/{strUserId}",
+            list="/api/{model_slug}/getList",
+            get_inactive_users="/api/{model_slug}/getInactiveUsers",
+            get_accounts_by_tenant="/api/{model_slug}/{tenantId}",
+            get_accounts_by_email_flag="/api/{model_slug}/{intTenantId}/{bEmailFlag}",
+            get_all_by_tenant="/api/{model_slug}/getAllByTenant/{intTenantId}",
+            filter_users="/api/{model_slug}/filterUsers/{intTenant}/{strSearch}/{bActive}/{strSortBy}/{strDirection}/{intPage}/{intPageSize}",
+            filter_user_roles="/api/{model_slug}/filterUserRoles/{intId}/{strRole}/{strSortBy}/{strDirection}/{intPage}/{intPageSize}",
+            change_user_status="/api/{model_slug}/changeUserStatus/{strId}/{bStatus}",
+            get_user_by_username="/api/{model_slug}/getUserByUsername/{strUsername}",
+            get="/api/{model_slug}/find/{id}",
+            get_roles="/api/{model_slug}/getRoles",
+            get_roles_by_user="/api/{model_slug}/getRolesByUser/{strUser}",
+            is_delegate="/api/{model_slug}/isDelegate/{strUser}",
+            get_delegates="/api/{model_slug}/getDelegates/{userId}",
+            change_avatar="/api/{model_slug}/changeAvatar/{strUsername}",
+        )
+
+    @classmethod
+    def get_tenant_id_for_user_id(cls, user_id: str) -> Optional[int]:
+        """
+        Retrieve all users by tenant ID.
+
+        Args:
+            user_id: str : user id to find
+
+        Returns:
+            Optional[int]: optionals
+        """
+        user = cls.get_user_by_id(user_id)
+        return user.tenantId if user else None
+
+    @classmethod
+    def get_user_by_id(cls, user_id: str) -> "User":
+        """
+        Get a user by their ID
+
+        :param str user_id: The user's ID
+        :return: The user object
+        :rtype: User
+        """
+        response = cls._get_api_handler().get(
+            endpoint=cls.get_endpoint("get").format(model_slug=cls._module_slug, id=user_id)
+        )
+        return cls._handle_response(response)
+
+    @classmethod
+    def get_all(cls) -> List["User"]:
+        """
+        Get all users from RegScale
+
+        :return: List of RegScale users
+        :rtype: List[User]
+        """
+        response = cls._get_api_handler().get(endpoint=cls.get_endpoint("get_all"))
+        return cast(List[T], cls._handle_list_response(response))
+
+    def assign_role(self, role_id: str) -> bool:
+        """
+        Assign a role to a user
+
+        :return: Whether the role was assigned
+        :rtype: bool
+        """
+        response = self._get_api_handler().post(
+            data={"roleId": role_id, "userId": self.id}, endpoint=self.get_endpoint("assign_role")
+        )
+        return response.ok

regscale/models/regscale_models/user_group.py

@@ -0,0 +1,55 @@
+"""
+UserGroup model for the RegScale API.
+"""
+
+from typing import Optional
+
+from pydantic import ConfigDict, Field
+
+from regscale.core.app.utils.app_utils import get_current_datetime
+from regscale.models import RegScaleModel
+
+
+class UserGroup(RegScaleModel):
+    _module_slug = "userGroups"
+
+    id: Optional[int] = None
+    groupsId: int
+    userId: str
+    isPublic: Optional[bool] = True
+    tenantsId: Optional[int] = 1
+    createdById: Optional[str] = Field(default_factory=RegScaleModel.get_user_id)
+    dateCreated: Optional[str] = Field(default_factory=get_current_datetime)
+    lastUpdatedById: Optional[str] = Field(default_factory=RegScaleModel.get_user_id)
+    dateLastUpdated: Optional[str] = Field(default_factory=get_current_datetime)
+
+    @staticmethod
+    def _get_additional_endpoints() -> ConfigDict:
+        """
+        Get additional endpoints for the UserGroup model.
+
+        :return: A dictionary of additional endpoints
+        :rtype: ConfigDict
+        """
+        return ConfigDict(
+            filter_user_groups="/api/{model_slug}/filterUserGroups/{intGroupId}/{intPage}/{intPageSize}",
+            # Get the list of users in the specified group (GET)
+            get_users_by_group="/api/userGroups/getUsersByGroup/{intGroupId}",
+            # Get the list of groups for a given user (GET)
+            get_groups_by_user="/api/userGroups/getGroupsByUser/{strUserId}",
+        )
+
+    @classmethod
+    def get_users_by_group(cls, group_id: int):
+        """
+        Get the list of users in the specified group.
+
+        :param group_id: The group ID
+        :return: A list of users
+        """
+        response = cls._get_api_handler().get(
+            endpoint=cls.get_endpoint("get_users_by_group").format(intGroupId=group_id)
+        )
+        if response and response.ok:
+            return response.json()
+        return []

regscale/models/regscale_models/vulnerability.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Model for Vulnerability in the application"""
+from enum import Enum
+from typing import List, Optional, Union
+from urllib.parse import urljoin
+from warnings import warn
+
+from pydantic import ConfigDict, Field
+from requests import Response
+
+from regscale.core.app.api import Api
+from regscale.core.app.application import Application
+from regscale.core.app.utils.app_utils import get_current_datetime
+from regscale.models import regscale_models
+from regscale.models.regscale_models.regscale_model import RegScaleModel
+
+
+def deprecated(message):
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            warn(f"{func.__name__} is deprecated. {message}", DeprecationWarning, stacklevel=2)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+class VulnerabilitySeverity(str, Enum):
+    """Vulnerability Severity"""
+
+    Low = "LOW"
+    Medium = "MEDIUM"
+    High = "HIGH"
+    Critical = "CRITICAL"
+
+
+class VulnerabilityStatus(str, Enum):
+    """Vulnerability Status"""
+
+    Open = "OPEN"
+    Closed = "CLOSED"
+
+
+class Vulnerability(RegScaleModel):
+    """Vulnerability Model"""
+
+    _module_slug = "vulnerability"
+    _unique_fields = [
+        ["plugInName", "parentId", "parentModule"],
+    ]
+
+    id: int = 0
+    createdById: str = Field(default_factory=RegScaleModel.get_user_id)
+    dateCreated: str = Field(default_factory=get_current_datetime)
+    lastUpdatedById: str = Field(default_factory=RegScaleModel.get_user_id)
+    dateLastUpdated: str = Field(default_factory=get_current_datetime)
+    uuid: Optional[str] = None
+    scanId: Optional[int] = None
+    parentId: Optional[int] = None
+    parentModule: Optional[str] = None
+    lastSeen: Optional[str] = None
+    firstSeen: Optional[str] = None
+    daysOpen: Optional[int] = None
+    dns: Optional[str] = None
+    ipAddress: Optional[str] = Field(default="")
+    mitigated: Optional[bool] = None
+    operatingSystem: Optional[str] = None
+    port: Optional[Union[str, int]] = None
+    protocol: Optional[str] = None
+    severity: Optional[Union[str, VulnerabilitySeverity]] = None
+    plugInName: Optional[str] = None
+    plugInId: Optional[int] = None
+    cve: Optional[str] = None
+    vprScore: Optional[Union[int, float]] = None
+    exploitAvailable: Optional[bool] = None
+    title: Optional[str] = None
+    cvsSv3BaseScore: Optional[Union[float, int]] = None
+    description: Optional[str] = None
+    plugInText: Optional[str] = None
+    tenantsId: int = Field(default=0)
+    isPublic: bool = Field(default=False)
+    dateClosed: Optional[str] = None
+    status: Optional[VulnerabilityStatus] = VulnerabilityStatus.Open
+
+    def __eq__(self, other) -> bool:
+        """
+        Check if two Vulnerability objects are equal is needed for comparison operations in flat file importer
+        :param other:
+        :return: True if the two objects are equal, False otherwise
+        :rtype: bool
+        """
+        if not isinstance(other, Vulnerability):
+            return False
+        return (
+            self.plugInName == other.plugInName
+            and self.parentId == other.parentId
+            and self.parentModule == other.parentModule
+            and self.ipAddress == other.ipAddress
+            and self.dns == other.dns
+        )
+
+    def __init__(self, **data):
+        # Map snake_case to camelCase before initialization
+        field_mappings = {
+            "scan_id": "scanId",
+            "parent_id": "parentId",
+            "parent_module": "parentModule",
+            "last_seen": "lastSeen",
+            "first_seen": "firstSeen",
+            "days_open": "daysOpen",
+            "ip_address": "ipAddress",
+            "operating_system": "operatingSystem",
+            "plugin_name": "plugInName",
+            "plugin_id": "plugInId",
+            "vpr_score": "vprScore",
+            "exploit_available": "exploitAvailable",
+            "cvss_v3_base_score": "cvsSv3BaseScore",
+            "plugin_text": "plugInText",
+            "tenants_id": "tenantsId",
+            "is_public": "isPublic",
+            "date_closed": "dateClosed",
+        }
+
+        # Convert snake_case keys to camelCase
+        for snake_key, camel_key in field_mappings.items():
+            if snake_key in data:
+                data[camel_key] = data.pop(snake_key)
+
+        super().__init__(**data)
+
+    @staticmethod
+    def _get_additional_endpoints() -> ConfigDict:
+        """
+        Get additional endpoints for the Vulnerability model, using {model_slug} as a placeholder for the model slug.
+
+        :return: A dictionary of additional endpoints
+        :rtype: ConfigDict
+        """
+        return ConfigDict(  # type: ignore
+            get_count="/api/{model_slug}/getCount",  # type: ignore
+            batch_create="/api/{model_slug}/batchCreate",  # type: ignore
+            find_by_guid="/api/{model_slug}/findByGUID/{strGUID}",  # type: ignore
+            drilldown="/api/{model_slug}/drilldown/{parentId}/{scanId}/{strSeverity}/{intPage}/"  # type: ignore
+            "{intPageSize}",
+            lookup_cve="/api/{model_slug}/lookupCVE/{strCVE}",  # type: ignore
+            get="/api/{model_slug}/find/{id}",  # type: ignore
+        )
+
+    @staticmethod
+    def determine_cvss3_severity_text(cvss_v3_base_score: float) -> str:
+        """
+        Determine CVSS3 Severity Text from CVSS3 Base Score
+
+        :param float cvss_v3_base_score: CVSS3 Base Score
+        :return: CVSS3 Severity Text
+        :rtype: str
+        """
+        results = "low"
+        if 4.0 <= cvss_v3_base_score <= 6.9:
+            results = "medium"
+        elif 7.0 <= cvss_v3_base_score <= 8.9:
+            results = "high"
+        elif cvss_v3_base_score > 8.9:
+            results = "critical"
+        return results
+
+    @staticmethod
+    @deprecated("Use Vulnerability.get_all_by_parent() instead")
+    def find_vulns_by_scan(app: Application, scan_id: int) -> List["Vulnerability"]:  # noqa: F841
+        """
+        Find Vulnerabilities by Scan ID
+
+        :param Application app: Application instance
+        :param int scan_id: Scan ID
+        :return: List of Vulnerabilities
+        :rtype: List[Vulnerability]
+        """
+        return Vulnerability.get_all_by_parent(parent_id=scan_id, parent_module=regscale_models.Scan.get_module_slug())
+
+    @classmethod
+    @deprecated("Use Vulnerability.create() instead")
+    def post_vulnerability(cls, vulnerability: "Vulnerability") -> Optional["Vulnerability"]:
+        """
+        Post a vulnerability to the API
+
+        :param Vulnerability vulnerability: The vulnerability to be posted
+        :return: The response from the API as a dictionary
+        :rtype: Optional["Vulnerability"]
+        """
+        return vulnerability.create()
+
+    @classmethod
+    @deprecated(
+        "Use Vulnerability.create() for individual vulnerabilities or Vulnerability.batch_create() for "
+        "multiple vulnerabilities"
+    )
+    def post_vulnerabilities(
+        cls,
+        app: Application,  # noqa: F841
+        vulnerabilities: List["Vulnerability"],
+        output_to_console: Optional[bool] = True,
+    ) -> List[Response]:
+        """
+        Insert new vulnerabilities into RegScale
+
+        :param Application app: Application object
+        :param List[Vulnerability] vulnerabilities: List of Vulnerability objects
+        :param Optional[bool] output_to_console: Whether to output to console, defaults to True
+        :return: A list of Responses
+        :rtype List[Response]
+        """
+        responses = []
+
+        def batch_post(url: str, dat: list[dict]) -> Response:
+            """
+            Simple wrapper to post a list of JSON data to a URL
+
+            :param str url: URL to post to
+            :param list[dict] dat: A list of JSON data to post
+            :return: Response object
+            :rtype: Response
+            """
+            return api.post(url=url, json=dat)
+
+        api = Api()
+        if output_to_console and vulnerabilities:
+            api.logger.info("Creating %i new vulnerabilities in RegScale...", len(vulnerabilities))
+        # Create batches of vulnerabilities to post
+        batch_size = 500
+        batches = [vulnerabilities[i : i + batch_size] for i in range(0, len(vulnerabilities), batch_size)]
+        for batch in batches:
+            res = batch_post(
+                url=urljoin(api.config["domain"], cls.get_endpoint("batch_create")),
+                dat=[vuln.model_dump() for vuln in batch],
+            )
+            if res.ok:
+                responses.extend(res.json())
+        if len(responses):
+            api.logger.info("Successfully created %i new vulnerabilities in RegScale", len(responses))
+        return responses