tenable_aws_sechub 2.2.2__py3-none-any.whl

tenable_aws_sechub/cli.py

@@ -0,0 +1,42 @@
+"""
+Simple CLI wrapper for commandline interaction with the integration.
+"""
+
+import logging
+from pathlib import Path
+from typing_extensions import Annotated
+import typer
+import tomlkit
+from rich.logging import RichHandler
+from .transform import Processor
+
+
+app = typer.Typer(add_completion=False)
+
+
+@app.command()
+def sechub(
+    configfile: Path = Path('tvm2aws.toml'),
+    verbose: Annotated[int, typer.Option('--verbose', '-v', max=5, count=True)] = 2,
+):
+    """
+    Tenable to AWS Security Hub vulnerability finding importer.
+    """
+    # Set the logging handler.
+    logging.basicConfig(
+        level=(5 - verbose) * 10,
+        datefmt='[%X]',
+        handlers=[RichHandler(rich_tracebacks=True)],
+    )
+
+    # Read the configuration file
+    with configfile.open('r', encoding='utf-8') as cobj:
+        config = tomlkit.load(cobj)
+
+    # Instantiate and run the ingestion processor.
+    processor = Processor(config)
+    processor.ingest()
+
+    # Write out the updated configuration file with the updated parameters.
+    with configfile.open('w', encoding='utf-8') as cobj:
+        tomlkit.dump(processor.config, cobj)

tenable_aws_sechub/finding.py

@@ -0,0 +1,184 @@
+"""
+The findings module handles transforming a TVM vulnerability finding into an
+AWS Security Hub finding.
+"""
+
+import logging
+from typing import Dict, List
+
+import arrow
+from restfly.utils import dict_clean, dict_flatten, trunc
+
+log = logging.getLogger('sechub.finding')
+
+SEV_MAP = {
+    0: [0, 'INFORMATIONAL'],
+    1: [10, 'LOW'],
+    2: [40, 'MEDIUM'],
+    3: [70, 'HIGH'],
+    4: [90, 'CRITICAL'],
+}
+
+STATE_MAP = {
+    'OPEN': 'ACTIVE',
+    'NEW': 'ACTIVE',
+    'REOPENED': 'ACTIVE',
+    'FIXED': 'ARCHIVED',
+}
+
+
+class Finding:
+    """
+    Security Hub Finding transformer
+    """
+
+    region: str
+    start_date: str
+
+    def __init__(
+        self,
+        region: str,
+    ):
+        self.region = region
+        # self.account_id = account_id
+        # self.map_to_asset_account = map_to_asset_account
+        self.start_date = arrow.now().isoformat()
+        # if allowed_accounts:
+        #     self.allowed_accounts = allowed_accounts
+        # elif map_to_asset_account and not allowed_accounts:
+        #     self.allowed_accounts = [account_id]
+
+    def check_required_params(self, vuln: Dict):
+        """
+        Checks to see if all of the required attributes exist for the finding
+        to be generated.  If validation fails, then a KeyError will be raised
+        detailing the missing keys or keys with empty data.
+
+        Args:
+            vuln (dict): The vuln object to check
+        """
+        # We only need to specify the asset fields that are required as these
+        # fields must never have a NoneType value in them.
+        required_attributes = [
+            'asset.cloud.aws.region',
+            'asset.cloud.aws.ec2_instance_id',
+            'asset.cloud.aws.owner_id',
+            'asset.cloud.aws.ec2_instance_type',
+            'asset.cloud.aws.ec2_instance_ami_id',
+        ]
+        failed = []
+        for attr in required_attributes:
+            if vuln.get(attr) is None:
+                failed.append(attr)
+        if failed:
+            raise KeyError(
+                (
+                    f'The required asset attributes {",".join(failed)}'
+                    f' were not set on asset {vuln["asset.uuid"]}'
+                )
+            )
+        # NOTE: Disabled the account checking as we will always be using the account
+        #       owner from the asset moving forward.
+        #
+        # if (
+        #     self.allowed_accounts
+        #     and vuln.get('asset.aws_owner_id') not in self.allowed_accounts
+        #     and self.map_to_asset_account
+        # ):
+        #     raise KeyError(
+        #         f'asset {vuln["asset.aws_owner_id"]}:{vuln["asset.uuid"]} is not within'
+        #         ' one of the allowed accounts.'
+        #     )
+
+    def generate(self, vuln: Dict) -> Dict:
+        """
+        Generates an AWS Security Hub finding based on the TVM asset and vuln
+        finding that was inputted
+
+        Args:
+            vuln (dict): The vuln object from the vuln export
+
+        Returns:
+            dict:
+                The transformed AWS Sechub finding
+        """
+        vuln = dict_flatten(vuln)
+        self.check_required_params(vuln)
+        normalized, label = SEV_MAP[vuln.get('severity_id', 0)]
+
+        finding = {
+            'SchemaVersion': '2018-10-08',
+            'FirstObservedAt': vuln['first_found'],
+            'LastObservedAt': vuln['last_found'],
+            'ProductArn': (
+                f'arn:aws:securityhub:{self.region}::product/tenable/vulnerability-management'
+            ),
+            'AwsAccountId': vuln['asset.cloud.aws.owner_id'],
+            'GeneratorId': f'tenable-plugin-{vuln["plugin.id"]}',
+            'Id': (
+                f'{vuln["asset.cloud.aws.region"]}/'
+                f'{vuln["asset.cloud.aws.ec2_instance_id"]}/'
+                f'{vuln["plugin.id"]}'
+            ),
+            'CreatedAt': self.start_date,
+            'UpdatedAt': self.start_date,
+            'Types': ['Software and Configuration Checks/Vulnerabilities/CVE'],
+            'Severity': {
+                'Label': label,
+                'Normalized': normalized,
+                'Original': vuln.get('severity', 'info'),
+            },
+            # Some plugin names run quite long, we will need to truncate to
+            # the max string size that AWS supports.
+            'Title': trunc(vuln['plugin.name'], 256),
+            # The description cannot exceed 1024 characters in size.
+            'Description': trunc(vuln['plugin.description'], 1024),
+            'Resources': [
+                {
+                    'Type': 'AwsEc2Instance',
+                    'Id': (
+                        'arn:aws:ec2:'
+                        f'{vuln["asset.cloud.aws.region"]}:'
+                        f'{vuln["asset.cloud.aws.owner_id"]}:'
+                        'instance:'
+                        f'{vuln["asset.cloud.aws.ec2_instance_id"]}'
+                    ),
+                    'Region': vuln['asset.cloud.aws.region'],
+                    'Details': {
+                        'AwsEc2Instance': {
+                            'Type': vuln['asset.cloud.aws.ec2_instance_type'],
+                            'ImageId': vuln['asset.cloud.aws.ec2_instance_ami_id'],
+                            'IpV4Addresses': vuln['asset.network.ipv4s']
+                            if vuln.get('asset.network.ipv4s')
+                            else None,
+                            'IpV6Addresses': vuln['asset.network.ipv6s']
+                            if vuln.get('asset.network.ipv6s')
+                            else None,
+                        },
+                    },
+                }
+            ],
+            'ProductFields': {
+                'CVE': ', '.join(vuln.get('plugin.cve', [])),
+                'Plugin Family': vuln['plugin.family'],
+                'Type': vuln['plugin.type'],
+            },
+            # Have to research if we want to continue to construct direct
+            # links into the relevant part of the UI.  This may be more
+            # complicated with the export workbenches than they were with the
+            # legacy workbenches.
+            # 'SourceUrl': 'XXXXXXX',
+            'Remediation': {
+                'Recommendation': {
+                    # The solution cannot exceed 1024 characters in length.
+                    'Text': trunc(vuln['plugin.solution'], 512)
+                    if vuln.get('plugin.solution')
+                    else None,
+                    'Url': vuln.get('plugin.see_also')[0]
+                    if vuln.get('plugin.see_also')
+                    else None,
+                }
+            },
+            'RecordState': STATE_MAP[vuln['state']],
+        }
+        return dict_clean(finding)

tenable_aws_sechub/transform.py

@@ -0,0 +1,194 @@
+"""
+Transform module handles connection to both APIs and the mechanics of pushing
+the data between them.
+"""
+
+import logging
+from typing import Any, Dict, List
+
+import arrow
+import boto3
+from restfly.utils import dict_flatten, dict_merge
+from tenable.io import TenableIO
+
+from .finding import Finding
+
+
+class Cache:
+    """
+    AWS Cache Profile
+    """
+
+    session: 'boto3.session.Session'
+    client: 'boto3.session.Session'
+    cache: List[Dict]
+    region: str
+    finding: Finding
+    limit: int
+    count: int
+
+    def __init__(self, region: str, profile: str, limit: int = 100):
+        self.region = region
+        self.finding = Finding(region=region)
+        self.cache = []
+        self.count = 0
+        self.limit = limit
+        self.session = boto3.session.Session(
+            profile_name=profile,
+            region_name=region,
+        )
+        self.client = self.session.client('securityhub')
+
+    def add(self, finding: Dict):
+        """
+        Adds the finding to the cache to be uploaded.  If the cache exceeds the max
+        size limit, then we will automatically push the cache up to SecurityHub.
+
+        Args:
+            finding: Merged TVM finding and asset metadata
+        """
+        transformed = self.finding.generate(finding)
+        self.count += 1
+        self.cache.append(transformed)
+        if len(self.cache) >= self.limit:
+            self.commit()
+
+    def commit(self):
+        """
+        Flushes the cache of findings up to Security Hub.
+        """
+        if len(self.cache) > 0:
+            self.client.batch_import_findings(Findings=self.cache)
+            self.cache = []
+
+
+class Processor:  # noqa PLR902
+    """
+    Main transform processor class.
+    """
+
+    tvm: TenableIO
+    aws_finding: Finding
+    since: int = 0
+    config: Dict
+    accounts: Dict[str, str]
+    caches: Dict[str, Cache]
+    states: List[str] = ['open', 'reopened', 'fixed']
+    sources: List[str] = ['CloudDiscoveryConnector']
+    severity: List[str] = ['high', 'critical']
+
+    def __init__(self, config: Dict):
+        # We will be maintining caches and boto3 sessions for each profile described
+        # within the configuration file.  As many accounts can also exist within a
+        # singular profile, we will also have an independent dictionary to store the
+        # mapping between account and profile.  This will mean that the "add" method
+        # will now automatically refuse any account_ids that arent in the mapping and
+        # instead throw a warning log message instead.
+        self.caches = {}
+        self.accounts = {}
+        for profile in config.get('aws_profile', []):
+            # For each profile defined, we will be creating a new session, client,
+            # cache, and build the account to profile linkages.
+            self.caches[profile['name']] = Cache(
+                region=profile['region'],
+                profile=profile['name'],
+                limit=config.get('upload_batch_size', 100),
+            )
+            for account in profile['accounts']:
+                self.accounts[str(account)] = profile['name']
+
+        self.config = config
+        self.since = config.get('since', self.since)
+        self.states = config.get('states', self.states)
+        self.sources = config.get('sources', self.sources)
+        self.severity = config.get('severity', self.severity)
+        self.tvm = TenableIO(
+            access_key=config.get('access_key'),
+            secret_key=config.get('secret_key'),
+            url=config.get('tvm_url', 'https://cloud.tenable.com'),
+        )
+        self._log = logging.getLogger('Tenb2SecHub')
+        self._log.debug(self.caches)
+        self._log.debug(self.accounts)
+
+    def get_trimmed_assets(self):
+        """
+        Retreives the asset metadata and then trims out the fields that we will
+        not be needing to merge into the finding data.  We do this in order to
+        ensure that we dont eat up any more memory than we need to.
+
+        Returns:
+            dict:
+                The dictionary of the trimmed assets.
+        """
+        ts = arrow.utcnow().shift(days=-30).timestamp()
+        if ts > self.since:
+            ts = self.since
+
+        assets = self.tvm.exports.assets_v2(since=ts)
+        trims = [
+            'network.ipv4s',
+            'network.ipv6s',
+            'cloud.aws.region',
+            'cloud.aws.ec2_instance_id',
+            'cloud.aws.owner_id',
+            'cloud.aws.ec2_instance_type',
+            'cloud.aws.ec2_instance_ami_id',
+        ]
+        trimmed = {}
+        for asset in assets:
+            a = dict_flatten(asset)
+            if a.get('cloud.aws.owner_id', None) not in self.accounts:
+                self._log.warning(f'Asset {a["id"]} not found in AWS account listing')
+                continue
+            trimmed[a['id']] = {k: v for k, v in a.items() if k in trims}
+            self._log.debug(f'Adding {a["id"]} to {a["cloud.aws.owner_id"]}')
+        return trimmed
+
+    def ingest(self):
+        """
+        Perform the finding ingestion into AWS Security Hub.
+        """
+        # Update the since parameter stored int he configuration to the current
+        # timestamp.
+        self.config['since'] = int(arrow.now().timestamp())
+
+        # Initiate the vulnerability export and get the trimmed asset data.
+        vulns = self.tvm.exports.vulns(
+            since=self.since, state=self.states, severity=self.severity
+        )
+        assets = self.get_trimmed_assets()
+
+        # For each vulnerability finding, we will merge in the associated
+        # asset metadata, then feed the merged information into the AWS
+        # finding generator.  If we successfully got a finding generated, then
+        # add that finding to the batch queue.
+        for vuln in vulns:
+            asset_obj = assets.get(vuln['asset']['uuid'])
+            if not asset_obj:
+                self._log.warning(
+                    f'No asset data for {vuln["asset"]["uuid"]} within asset cache.  '
+                    f'Not reporting plugin {vuln["plugin"]["id"]}.'
+                )
+                continue
+            aws_account = asset_obj['cloud.aws.owner_id']
+            profile_id = self.accounts.get(aws_account)
+            vuln['asset'] = dict_merge(vuln['asset'], asset_obj)
+            try:
+                self._log.debug(vuln)
+                self.caches[profile_id].add(vuln)
+            except Exception as err:
+                self._log.warning(
+                    (
+                        f'Asset {vuln["asset"]["uuid"]} finding '
+                        f'{vuln["plugin"]["id"]} failed to add '
+                        f'with error: {err}'
+                    )
+                )
+
+        # Commit any remaining findings in the queues to AWS.
+        for _, cache in self.caches.items():
+            cache.commit()
+
+        for profile, cache in self.caches.items():
+            self._log.info(f'Sent {cache.count} events to profile {profile}')

tenable_aws_sechub/version.py

@@ -0,0 +1 @@
+version = '2.2.2'

tenable_aws_sechub-2.2.2.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: tenable_aws_sechub
+Version: 2.2.2
+Summary: Tenable Vulnerability Management to AWS Security Hub
+Author-email: "Tenable, Inc." <smcgrath@tenable.com>
+License: MIT License
+Project-URL: Homepage, https://github.com/tenable/Security-Hub
+Project-URL: Repository, https://github.com/tenable/Security-Hub
+Project-URL: Issues, https://github.com/tenable/Security-Hub/issues
+Project-URL: Changelog, https://github.com/tenable/Security-Hub/blob/main/CHANGELOG.md
+Keywords: tenable,tenable vulnerability management,tenable security center,tenable.io,tenable.sc,aws,security hub
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: System :: Systems Administration
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Description-Content-Type: text/markdown
+Requires-Dist: arrow>=1.3.0
+Requires-Dist: restfly>=1.4.5
+Requires-Dist: typer>=0.9.0
+Requires-Dist: tomlkit>=0.12.4
+Requires-Dist: rich>=13.3.1
+Requires-Dist: boto3>=1.34.68
+Requires-Dist: pytenable>=1.5.0
+
+# Tenable Vulnerability Management to AWS Transformer
+
+| :exclamation: | If upgrading from v1 please read the upgrade section |
+| ------------- | :--------------------------------------------------- |
+
+This tool is designed to consume Tenable.io asset and vulnerability data,
+transform that data into the AWS Security Hub Finding format, and then upload
+the resulting data into AWS Security Hub.
+
+The tool can be run as either a one-shot docker container or as a command-line
+tool. To run as a docker image, you'll need to build the image and then pass
+the config file to the container.
+
+## Requirements
+
+- The Tenable Vulnerability Management Integration for Security Hub must be
+  configured to accept findings from the integration.
+- At a minimum the configuration file must have the account id that the events
+  will be sent to. Ideally the region should be configured as well.
+- A set of API Keys within TVM should be configured to allow exportation of
+  assets and vulnerability findings from the platform. These keys should be
+  wither configured within the configuration file or as environment variables
+
+## Installation
+
+```
+pip install tenable_aws_sechub
+```
+
+## Upgrading from v1
+
+If you are upgrading from the original version of the integration, please note
+that there are some additional steps that need to be taken as the ARN that is
+used has changed.
+
+1. Disable the Tenable.io SecurityHub integration
+2. Enable the Tenable Vulnerability Management integration
+3. Configure and run the updated integration (this code)
+
+## Configuration
+
+Simply build a configuration file (or use the [example file][cfg] provided)
+with the following details:
+
+```toml
+access_key = "1234567890abcdef1234567890"
+secret_key = "1234567890abcdef1234567890"
+
+[[aws_profile]]
+name = "default"
+accounts = [1234567890]
+region = "us-east-1"
+```
+
+Once the configuration file is saved, go ahead and ensure that the AWS CLI can
+communicate to AWS, or generate the appropriate configuration parameters that
+AWS needs for their boto3 client. Details for how to do this is documented
+below:
+
+1. [Boto3 Configuration](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#configuration)
+2. [AWS CLI Config](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)
+
+## Running the integration
+
+```
+❯ tvm2aws --configfile /path/to/config.toml
+```
+
+## Commandline options
+
+```
+❯ tvm2aws --help
+
+ Usage: tvm2aws [OPTIONS]
+
+ Tenable to AWS Security Hub vulnerability finding importer.
+
+╭─ Options ───────────────────────────────────────────────────────────────────╮
+│ --configfile          PATH                  [default: tvm2aws.toml]         │
+│ --verbose     -v      INTEGER RANGE [x<=5]  [default: 2]                    │
+│ --help                                      Show this message and exit.     │
+╰─────────────────────────────────────────────────────────────────────────────╯
+```
+
+[cfg]: tvm2aws.toml

tenable_aws_sechub-2.2.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+tenable_aws_sechub/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tenable_aws_sechub/cli.py,sha256=t8PQrWLU-3bDA5S2nTr35Jc__UvozYMHH0k0efqjmYo,1130
+tenable_aws_sechub/finding.py,sha256=-vDA1oanhF9arhc6Q1r8dXyrCQziajM4gkPhq4xSRE4,6682
+tenable_aws_sechub/transform.py,sha256=_e2xCn1eCHtQzemlD1CEUAjgyXFwb1anc87_ETMoAU8,6950
+tenable_aws_sechub/version.py,sha256=WOvKCVRGotc0tr7twRMrSkDXzWTRPTrEpeC-vKBt-ls,18
+tenable_aws_sechub-2.2.2.dist-info/METADATA,sha256=KdXJK96SC8VAsLMV78yx-BZ4DOsbF5oarnbhZ-ePijo,4455
+tenable_aws_sechub-2.2.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+tenable_aws_sechub-2.2.2.dist-info/entry_points.txt,sha256=Xx4sBElx9pXAoT47aoDOF4EWrfVkAMPHOARKzkSfJ3Q,55
+tenable_aws_sechub-2.2.2.dist-info/top_level.txt,sha256=O8dwicvnN5Vl5pBurXF5KwYsDt-BZOmv46eztwQKf4A,19
+tenable_aws_sechub-2.2.2.dist-info/RECORD,,

tenable_aws_sechub-2.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tenable_aws_sechub-2.2.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tvm2aws = tenable_aws_sechub.cli:app

tenable_aws_sechub-2.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+tenable_aws_sechub