gitlabcis 1.3.2__py3-none-any.whl

gitlabcis/tests/unit/utils/utils_general_test.py

@@ -0,0 +1,149 @@
+# -----------------------------------------------------------------------------
+
+from collections import namedtuple
+from unittest.mock import Mock, mock_open, patch
+
+import pytest
+import yaml
+
+from gitlabcis.utils import (countRecommendations, mapRecommendations,
+                             readRecommendations, readYaml)
+
+# -----------------------------------------------------------------------------
+
+
+def test_count_recommendations():
+    assert countRecommendations() == 123
+
+# -----------------------------------------------------------------------------
+
+
+def test_read_recommendations():
+    # options:
+    ArgFilters = namedtuple(
+        'ArgFilters', ['profile', 'recommendation_ids', 'cis_controls',
+                       'implementation_groups', 'skip_recommendation_ids'])
+
+    # controls:
+    control1 = {
+        'id': '1.1.1', 'profile': '1',
+        'cis_controls': [{'id': '2.4', 'implementation_groups': 'IG2'}]}
+
+    control2 = {
+        'id': '1.1.12', 'profile': '2',
+        'cis_controls': [{'id': '16.1', 'implementation_groups': 'IG3'}]}
+
+    # run:
+    @patch('gitlabcis.utils.Path')
+    @patch('gitlabcis.utils.readYaml')
+    def run_test(mock_read_yaml, mock_path, arg_filters=None,
+                 expected_result=None, expect_exit=False):
+        mock_path.return_value.exists.return_value = True
+        mock_path.return_value.rglob.return_value = ['file1.yml', 'file2.yml']
+        mock_read_yaml.side_effect = [control1, control2]
+
+        if expect_exit:
+            mock_path.return_value.exists.return_value = False
+            with pytest.raises(SystemExit):
+                readRecommendations(arg_filters)
+        else:
+            result = readRecommendations(arg_filters)
+            assert result == expected_result
+
+    # Test no filters
+    run_test(expected_result=[control1, control2])
+
+    # Test profile filter
+    run_test(
+        arg_filters=ArgFilters(profile='1', recommendation_ids=None,
+                               cis_controls=None, implementation_groups=None,
+                               skip_recommendation_ids=None),
+        expected_result=[control1]
+    )
+
+    # Test recommendation_ids filter
+    run_test(
+        arg_filters=ArgFilters(profile=None, recommendation_ids=['1.1.12'],
+                               cis_controls=None, implementation_groups=None,
+                               skip_recommendation_ids=None),
+        expected_result=[control2]
+    )
+
+    # Test skip_recommendation_ids filter
+    run_test(
+        arg_filters=ArgFilters(profile=None, recommendation_ids=None,
+                               cis_controls=None, implementation_groups=None,
+                               skip_recommendation_ids=['1.1.12']),
+        expected_result=[control1]
+    )
+
+    # Test cis_controls filter
+    run_test(
+        arg_filters=ArgFilters(profile=None, recommendation_ids=None,
+                               cis_controls=['16.1'],
+                               implementation_groups=None,
+                               skip_recommendation_ids=None),
+        expected_result=[control2]
+    )
+
+    # Test implementation_groups filter
+    run_test(
+        arg_filters=ArgFilters(profile=None, recommendation_ids=None,
+                               cis_controls=None,
+                               implementation_groups=['IG2'],
+                               skip_recommendation_ids=None),
+        expected_result=[control1]
+    )
+
+    # Test directory not found
+    run_test(expect_exit=True)
+
+# -----------------------------------------------------------------------------
+
+
+def test_read_yaml():
+    example_input = "key1: value1\nkey2: value2"
+    example_output = {'key1': 'value1', 'key2': 'value2'}
+
+    # Test successful read
+    with patch('builtins.open', new_callable=mock_open,
+               read_data=example_input):
+        result = readYaml('dummy_path.yml')
+        assert result == example_output
+
+    # Test file not found
+    with patch('builtins.open', side_effect=FileNotFoundError), \
+         patch('sys.exit') as mock_exit, \
+         pytest.raises(SystemExit):
+        readYaml('non_existent_file.yml')
+        mock_exit.assert_called_once_with(1)
+
+    # Test logging
+    with patch('builtins.open', new_callable=mock_open,
+               read_data=example_input), \
+         patch('logging.debug') as mock_debug:
+        readYaml('test_file.yml')
+        mock_debug.assert_called_once_with('Opening: test_file.yml')
+
+    # Test invalid YAML content
+    with patch('builtins.open', new_callable=mock_open,
+               read_data="invalid: yaml: content"), \
+            pytest.raises(yaml.YAMLError):
+        readYaml('invalid_yaml.yml')
+
+# -----------------------------------------------------------------------------
+
+
+def test_map_recommendations():
+    functionList = [
+        Mock(__name__='func1'),
+        Mock(__name__='func2'),
+        Mock(__name__='func3')
+    ]
+
+    recommendations = [{'name': 'func1'}, {'name': 'func2'},
+                       {'name': 'func3'}]
+
+    assert len(
+        mapRecommendations(functionList, recommendations)
+    ) == 3

gitlabcis/tests/unit/utils/version_test.py

@@ -0,0 +1,11 @@
+# -----------------------------------------------------------------------------
+
+from gitlabcis import __version__
+
+import re
+
+# -----------------------------------------------------------------------------
+
+
+def test_gitlabcis_version():
+    assert re.match(r'^\d+\.\d+\.\d+$', __version__) is not None

gitlabcis/tests/unit/yaml/bad_file_test.py

@@ -0,0 +1,15 @@
+# -----------------------------------------------------------------------------
+
+import pytest
+
+# -----------------------------------------------------------------------------
+
+
+def test_bad_file(capsys):
+
+    with pytest.raises(SystemExit) as execCtx:
+        from gitlabcis.utils import readYaml  # noqa: F401
+
+        readYaml('non-existant.yml')
+
+    assert execCtx.value.code == 1

gitlabcis/tests/unit/yaml/recommendation_test.py

@@ -0,0 +1,123 @@
+# -----------------------------------------------------------------------------
+
+
+def test_valid_yaml_syntax(recommendations):
+    """
+    This test ensures that all the required keys are present in the yaml
+    recommendation
+    """
+
+    # the required keys of the yaml file:
+    requiredKeys = [
+        'id', 'name', 'title', 'profile', 'category', 'sub_category',
+        'description', 'rationale', 'impact', 'audit', 'remediation',
+        'default_value', 'references', 'cis_controls', 'additional_info'
+    ]
+
+    requiredKeys.sort()
+
+    for yamlName, yamlData in recommendations.items():
+        print(f'    - Testing: {yamlData.get("id")} - {yamlName}')  # noqa: E221,E501
+
+        yamlKeys = list(yamlData.keys())
+        yamlKeys.sort()
+
+        assert yamlKeys == requiredKeys
+
+# -----------------------------------------------------------------------------
+
+
+def test_categories(recommendationDirs, recommendations):
+    """
+    This test ensures that the category inside the yaml recommendation
+    matches those of the directories under /recommendations.
+    """
+
+    for yamlName, yamlData in recommendations.items():
+        print(f'    - Testing: {yamlData.get("id")} - {yamlName}')  # noqa: E221,E501
+
+        _expectedPath = (
+            f'{yamlData.get("category")}_{yamlData.get("id").split(".")[0]}'
+        )
+        assert _expectedPath in recommendationDirs
+
+# -----------------------------------------------------------------------------
+
+
+def test_sub_categories(recommendationDirs, recommendations):
+    """
+    This test ensures that the sub_category match those of the directories
+    under /recommendations.
+    """
+
+    for yamlName, yamlData in recommendations.items():
+        print(f'    - Testing: {yamlData.get("id")} - {yamlName}')  # noqa: E221,E501
+
+        _idSplit = yamlData.get('id').split('.')
+        _expectedPath = (
+            f'{yamlData.get("sub_category")}_{_idSplit[0]}_{_idSplit[1]}'
+        )
+
+        assert _expectedPath in recommendationDirs
+
+# -----------------------------------------------------------------------------
+
+
+def test_duplicate_ids(recommendations):
+    """
+    This test ensures that there are no duplicate IDs in the yaml files.
+    """
+
+    _ids = []
+
+    for yamlName, yamlData in recommendations.items():
+
+        print(f'    - Testing: {yamlData.get("id")} - {yamlName}')  # noqa: E221,E501
+
+        if yamlData['id'] in _ids:
+            raise AssertionError(
+                f'Duplicate ID: {yamlData["id"]} found in file: {yamlName}'
+            )
+        _ids.append(yamlData['id'])
+
+# -----------------------------------------------------------------------------
+
+
+def test_duplicate_names(recommendations):
+    """
+    This test ensures that there are no duplicate names in the yaml files.
+    """
+
+    _names = []
+
+    for yamlName, _yamlData in recommendations.items():
+        if yamlName in _names:
+            raise AssertionError(
+                f'Duplicate Name: {yamlName} found in {yamlName}')
+        _names.append(yamlName)
+
+# -----------------------------------------------------------------------------
+
+
+def test_template_values(recommendations):
+    """
+    This test ensures that there are no template values still in the file.
+    """
+
+    for yamlName, yamlData in recommendations.items():
+
+        _checks = []
+
+        print(f'    - Testing: {yamlData.get("id")} - {yamlName}')  # noqa: E221,E501
+
+        for key, value in yamlData.items():
+
+            # for list items:
+            if key == 'references' and value:
+                _checks.append('example' not in [v for v in value])
+
+            # for single value items:
+            else:
+                _checks.append(value != 'example')
+
+            assert False not in _checks

gitlabcis/utils/__init__.py

@@ -0,0 +1,146 @@
+# -------------------------------------------------------------------------
+
+import logging
+from pathlib import Path
+from sys import exit
+
+import yaml
+
+from . import ci  # noqa: F401
+
+# -----------------------------------------------------------------------------
+# count recommendations:
+# -----------------------------------------------------------------------------
+
+
+def countRecommendations():
+    return len(list(
+        Path(f'{Path(__file__).parent.parent}/recommendations').rglob('*.yml')
+    ))
+
+# -----------------------------------------------------------------------------
+# Load the recommendations:
+# -----------------------------------------------------------------------------
+
+
+def readRecommendations(argFilters=None):
+
+    _rDir = Path(f'{Path(__file__).parent.parent}/recommendations')
+
+    logging.debug(f'recommendations directory: {_rDir}')
+
+    if not _rDir.exists():
+        print(
+            f'Error: Recommendations directory {_rDir} was not found'
+        )
+        exit(1)
+
+    # -------------------------------------------------------------------------
+    # Gather all recommendations:
+    # -------------------------------------------------------------------------
+
+    recommendationFiles = list(_rDir.rglob('*.yml'))
+
+    if argFilters is None:
+
+        recommendations = [readYaml(r) for r in recommendationFiles]
+        logging.debug(f'Loaded: {len(recommendations)} recommendations')
+
+        return recommendations
+
+    # -------------------------------------------------------------------------
+    # Filter recommendations based on user input:
+    # -------------------------------------------------------------------------
+
+    logging.debug(f'Filtering with args: {argFilters}')
+
+    recommendations = []
+
+    for r in recommendationFiles:
+
+        yamlData = readYaml(r)
+
+        cisControls = yamlData.get('cis_controls', [])
+
+        # ---------------------------------------------------------------------
+
+        # if a profile was provided and it doesn't match in the recommendation:
+        if argFilters.profile:
+            if argFilters.profile != yamlData.get('profile'):
+                continue
+
+        # if a recommendation id was provided but it doesn't match:
+        if argFilters.recommendation_ids:
+            if yamlData.get('id') not in argFilters.recommendation_ids:
+                continue
+
+        # if a user wishes to skip certain recommendation id's:
+        if argFilters.skip_recommendation_ids:
+            if yamlData.get('id') in argFilters.skip_recommendation_ids:
+                continue
+
+        # ---------------------------------------------------------------------
+        # Iterate through the CIS Controls:
+        # ---------------------------------------------------------------------
+
+        # if a CIS Control ID was provided and it's not found:
+        if argFilters.cis_controls:
+            _cisIds = set([cis.get('id') for cis in cisControls])
+
+            if not set(argFilters.cis_controls).intersection(_cisIds):
+                continue
+
+        # if an implementation group was provided and it's not found:
+        if argFilters.implementation_groups:
+
+            if not set(argFilters.implementation_groups).intersection(
+                set([
+                    control.get('implementation_groups')
+                    for control in cisControls
+                    ])):
+                continue
+
+        # for everything else, append it, this allows a user to pass no
+        # args and they return all the recommendations...
+        recommendations.append(yamlData)
+
+    return recommendations
+
+# -----------------------------------------------------------------------------
+# Read a recommendation file:
+# -----------------------------------------------------------------------------
+
+
+def readYaml(recommendation):
+    """
+    Desc: This function takes a str path to a yaml file, reads it and
+          returns it.
+    """
+
+    logging.debug(f'Opening: {recommendation}')
+
+    try:
+        with open(recommendation, 'r') as f:
+            return yaml.safe_load(f)
+    except FileNotFoundError:
+        print(f'Error: Failed to find recommendation: {recommendation}')
+        exit(1)
+
+# -----------------------------------------------------------------------------
+# Map functions to recommendations:
+# -----------------------------------------------------------------------------
+
+
+def mapRecommendations(functionList, recommendationList):
+    """
+    Desc: This function maps a function to its relevant recommendation
+          It accepts a list of functions, and a list of recommendation dicts.
+    """
+
+    mappedFuncs = {func.__name__: func for func in functionList}
+
+    return {
+        mappedFuncs[recommendation['name']]: recommendation
+        for recommendation in recommendationList
+        if recommendation['name'] in mappedFuncs
+    }

gitlabcis/utils/ci.py

@@ -0,0 +1,132 @@
+# -------------------------------------------------------------------------
+
+
+def getConfig(glEntity, glObject, **kwargs):
+    """
+    This function attempts to obtain the .gitlab-ci.yml file.
+
+    The filepath can be:
+        - Remote: e.g. https://example.com/.gitlab-ci.yml
+        - External: e.g. rel/path/.gitlab-ci.yml@my/project:refName
+        - Local: e.g. custom/local/repo/path/.gitlab-ci.yml
+
+    Ref: https://docs.gitlab.com/ee/ci/pipelines/settings.html#specify-a-custom-cicd-configuration-file  # noqa: E501
+
+    Because remote links can potentially include any type of file, they are
+    not supported.
+
+    The function returns a dict in the similar manner as the benchmarks:
+
+    Examples:
+        - SKIP: {None: 'reason'}
+        - FAIL: {False: 'reason'}
+        - PASS: {ProjectFile, None}
+    """
+
+    import logging
+    import re
+
+    from gitlab.exceptions import (GitlabAuthenticationError, GitlabGetError,
+                                   GitlabHttpError)
+
+    try:
+        # set the default path if one is not set:
+        gitlabCiYamlPath = (
+            str(glEntity.ci_config_path)
+            if glEntity.ci_config_path != ''
+            else '.gitlab-ci.yml'
+        )
+
+        # SKIP remote CI files:
+        if '://' in gitlabCiYamlPath:
+            return {None: f'Remote CI file: {gitlabCiYamlPath} not supported'}
+
+        # handle different project locations:
+        remote = re.match(
+            r'(?P<filePath>.*)@(?P<namespace>.*):?(?P<refName>.*)',
+            gitlabCiYamlPath)
+
+        # define the location:
+        if remote is not None:
+            _tempEntity = glObject.projects.get(
+                remote.group('namespace')
+            )
+            _tempRef = remote.group('refName')
+            _tempPath = remote.group('filePath')
+        else:
+            _tempEntity = glEntity
+            _tempRef = glEntity.default_branch
+            _tempPath = gitlabCiYamlPath
+
+        # obtain the CI config file:
+        gitlabCiYaml = None
+        try:
+            gitlabCiYaml = _tempEntity.files.get(
+                file_path=_tempPath,
+                ref=_tempRef
+            )
+        except (GitlabHttpError, GitlabGetError) as e:
+            if e.response_code == 404:
+                logging.debug(f'No CI config file found at: {_tempPath}')
+                return {False: f'Pipeline config file not found: {_tempPath}'}
+
+        # return a dict with a ProjectFile class var as the key
+        # to differentiate results or not:
+        if gitlabCiYaml is not None:
+            return {gitlabCiYaml: None}
+
+        return {False: f'Pipeline config file not found: {_tempPath}'}
+
+    except (GitlabHttpError, GitlabGetError, GitlabAuthenticationError):
+        return {None: 'Insufficient permissions'}
+
+    # this is for pytest to run unauthed tests:
+    except AttributeError:
+        return {None: 'Insufficient permissions'}
+
+# -------------------------------------------------------------------------
+
+
+def searchConfig(glEntity, glObject, searchString, **kwargs):
+    """
+    This function allows to search for a string inside the .gitlab-ci.yml file
+
+    It uses the above getConfig() function to obtain it, then checks the str
+    based on its lowercase value.
+    """
+
+    import base64
+
+    from gitlab.exceptions import (GitlabAuthenticationError, GitlabGetError,
+                                   GitlabHttpError)
+    from gitlab.v4.objects.files import ProjectFile
+
+    try:
+        # obtain the ci config file:
+        gitlabCiYaml = getConfig(
+            glEntity, glObject, **kwargs)
+
+        # obtain the result:
+        try:
+            _result = next(iter(gitlabCiYaml))
+
+        # a SKIP was identified:
+        except TypeError:
+            # ensure the reason is returned:
+            return {None: gitlabCiYaml[None]}
+
+        # ensure we actually found the file:
+        if not isinstance(_result, ProjectFile):
+            return {_result: gitlabCiYaml[_result]}
+
+        yamlContents = base64.b64decode(
+            _result.content).decode('utf-8')
+
+        if searchString.lower() in yamlContents.lower():
+            return {True: f'{searchString} was found in CI config file'}
+        else:
+            return {False: f'{searchString} was not found in CI config file'}  # noqa: E713, E501
+
+    except (GitlabHttpError, GitlabGetError, GitlabAuthenticationError) as e:
+        if e.response_code in [401, 403]:
+            return {None: 'Insufficient permissions'}

gitlabcis-1.3.2.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 GitLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy 
+of this software and associated documentation files (the "Software"), to deal 
+in the Software without restriction, including without limitation the rights 
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
+copies of the Software, and to permit persons to whom the Software is 
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
+SOFTWARE.