{"_id":"@bastienbyra/cpe-mapper","_rev":"12-308cc40babc1d3e6aada5124f5c281de","name":"@bastienbyra/cpe-mapper","dist-tags":{"latest":"1.2.0","fix":"1.1.0-fix1"},"versions":{"1.0.0":{"name":"@bastienbyra/cpe-mapper","version":"1.0.0","keywords":["security","cpe","nvd","vulnerability","sbom","cyclonedx"],"author":{"name":"Bastien BYRA"},"license":"Apache-2.0","_id":"@bastienbyra/cpe-mapper@1.0.0","maintainers":[{"name":"bastienbyra","email":"byra.bastien@gmail.com"}],"homepage":"https://github.com/BastienBYRA/CPE-Mapper#readme","bugs":{"url":"https://github.com/BastienBYRA/CPE-Mapper/issues"},"bin":{"cpe-mapper":"src/cli.js"},"dist":{"shasum":"38056ccefb00fd3c6bd79f2c53356aae6264afcb","tarball":"https://registry.npmjs.org/@bastienbyra/cpe-mapper/-/cpe-mapper-1.0.0.tgz","fileCount":9,"integrity":"sha512-oAiDoY/EEWcMR60uoy38QRLde6WCwIW6FG4pwn9fAvGFcSPh+TjJN2EvGRXTlLsNROerjVgJmDLl1rd+AE7I4A==","signatures":[{"sig":"MEUCIQDMjCzCV3unBkAVBfdGy1ifkLImtOjvN0A11WdS7+VMOgIge3A4JCAQdTl+1WuljgVIa3D7QXzvjQsQg7jmPky4qI0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bastienbyra%2fcpe-mapper@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":35046},"main":"src/cli.js","type":"module","gitHead":"c1e3ae13b7bceebad6e27a047d71afc31eef5fa0","scripts":{"help":"node src/cli.js help","test":"NODE_ENV=test node --test","start":"node src/cli.js","wtest":"set NODE_ENV=test&& node --test","test-apply":"node src/cli.js apply -i testdata/bom.test.json -o testdata/result.test.json","update-version":"scripts/update-version.sh"},"_npmUser":{"name":"bastienbyra","email":"byra.bastien@gmail.com"},"repository":{"url":"git+https://github.com/BastienBYRA/CPE-Mapper.git","type":"git"},"_npmVersion":"10.9.3","description":"CPE-mapper is a CLI tool and JSON-based database designed to accurately map software package names to their corresponding CPEs (Common Platform Enumerations). Its main goal is to improve vulnerability identification in cases where standard package names f","directories":{},"_nodeVersion":"22.20.0","dependencies":{"commander":"^14.0.1","env-paths":"^3.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cpe-mapper_1.0.0_1759678536918_0.0015359367621354814","host":"s3://npm-registry-packages-npm-production"}},"1.1.0-fix1":{"name":"@bastienbyra/cpe-mapper","version":"1.1.0-fix1","keywords":["security","cpe","nvd","vulnerability","sbom","cyclonedx"],"author":{"name":"Bastien BYRA"},"license":"Apache-2.0","_id":"@bastienbyra/cpe-mapper@1.1.0-fix1","maintainers":[{"name":"bastienbyra","email":"byra.bastien@gmail.com"}],"homepage":"https://github.com/BastienBYRA/CPE-Mapper#readme","bugs":{"url":"https://github.com/BastienBYRA/CPE-Mapper/issues"},"bin":{"cpe-mapper":"src/cli.js"},"dist":{"shasum":"dfd99b09fc2037bb0eb7b3dc53d49a20212b5336","tarball":"https://registry.npmjs.org/@bastienbyra/cpe-mapper/-/cpe-mapper-1.1.0-fix1.tgz","fileCount":21,"integrity":"sha512-3BCzhTF9//qptwEEOQiL+Sb71Op94ki9ch9hjT11T4tS45aHVoye0HU6IIFQIsBYOIvS64OHZZMPD8CWaxmmeQ==","signatures":[{"sig":"MEQCIFvP8LJvrj1bHwIUJAFayLA2RZL1mCVeHR9fO+nCzHscAiBkxxeMmyPybD8ZKewQyS4P+2PqTK68rllcEfNYsy2/sg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":55783},"main":"src/cli.js","type":"module","gitHead":"4c7e1f795be6f0035cae0d5fd87f77d5d47d6628","scripts":{"help":"node src/cli.js help","test":"NODE_ENV=test node --test","start":"node src/cli.js","wtest":"set NODE_ENV=test&& node --test","test-apply":"node src/cli.js apply -i testdata/bom.test.json -o testdata/result.test.json","update-version":"scripts/update-version.sh"},"_npmUser":{"name":"bastienbyra","email":"byra.bastien@gmail.com"},"repository":{"url":"git+https://github.com/BastienBYRA/CPE-Mapper.git","type":"git"},"_npmVersion":"11.6.0","description":"CPE-mapper is a CLI tool and JSON-based database designed to accurately map software package names to their corresponding CPEs (Common Platform Enumerations). Its main goal is to improve vulnerability identification in cases where standard package names f","directories":{},"_nodeVersion":"22.11.0","dependencies":{"commander":"^14.0.1","env-paths":"^3.0.0"},"_hasShrinkwrap":false,"readmeFilename":"README.md","_npmOperationalInternal":{"tmp":"tmp/cpe-mapper_1.1.0-fix1_1759948006978_0.6633760063275449","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@bastienbyra/cpe-mapper","version":"1.2.0","description":"CPE-mapper is a CLI tool and JSON-based database designed to accurately map software package names to their corresponding CPEs (Common Platform Enumerations). Its main goal is to improve vulnerability identification in cases where standard package names f","main":"src/cli.js","type":"module","scripts":{"start":"node src/cli.js","help":"node src/cli.js help","test":"NODE_ENV=test node --test","wtest":"set NODE_ENV=test&& node --test","test-cov":"NODE_ENV=test node --experimental-test-coverage --test","wtest-cov":"set NODE_ENV=test&& node --experimental-test-coverage --test","test-apply-cdx":"node src/cli.js apply -i testdata/cyclonedx/bom.test.json -o testdata/cyclonedx-tests-gen/result.test.json","test-apply-spdx":"node src/cli.js apply -i testdata/spdx/bom.test.json -o testdata/spdx-tests-gen/result.test.json","update-version":"scripts/update-version.sh","sbom":"npm sbom --sbom-format cyclonedx","lint":"eslint .","lint:fix":"eslint . --fix"},"repository":{"type":"git","url":"git+https://github.com/BastienBYRA/CPE-Mapper.git"},"author":{"name":"Bastien BYRA"},"license":"Apache-2.0","bugs":{"url":"https://github.com/BastienBYRA/CPE-Mapper/issues"},"keywords":["security","cpe","nvd","vulnerability","sbom","cyclonedx"],"homepage":"https://github.com/BastienBYRA/CPE-Mapper#readme","dependencies":{"commander":"^14.0.1","env-paths":"^3.0.0"},"bin":{"cpe-mapper":"src/cli.js"},"devDependencies":{"@eslint/js":"^9.37.0","eslint":"^9.37.0","globals":"^16.4.0"},"_id":"@bastienbyra/cpe-mapper@1.2.0","gitHead":"06138d86114d7b95b4ec14148d2d804f33751b9a","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-tICxquB+g4HJ4n6Ojlf0LhxoRoVC5aFQ1fXxIquMABtxdrjVsleGgV+s2JBcACDR/SfT65e128d/HNOIJcnQxg==","shasum":"ae226bca490fc741e0beef1d88c392b07213804d","tarball":"https://registry.npmjs.org/@bastienbyra/cpe-mapper/-/cpe-mapper-1.2.0.tgz","fileCount":21,"unpackedSize":59502,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bastienbyra%2fcpe-mapper@1.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCyImK7hQ8dGQRyadJd2QYWw9IlWQoyk5VHYvLArcxZngIhAJX5GC20VN93JDjDNUHQaSOUOZGBDBNCf/O9W1boW9V3"}]},"_npmUser":{"name":"bastienbyra","email":"byra.bastien@gmail.com"},"directories":{},"maintainers":[{"name":"bastienbyra","email":"byra.bastien@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cpe-mapper_1.2.0_1763892641901_0.3639855424716236"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-05T15:35:36.815Z","modified":"2025-11-23T10:10:42.657Z","0.1.0":"2025-10-03T08:30:53.752Z","0.1.1":"2025-10-05T13:10:18.086Z","0.1.2":"2025-10-05T13:15:49.151Z","1.0.0":"2025-10-05T15:35:37.106Z","1.1.0":"2025-10-08T12:01:24.578Z","1.1.0-fix1":"2025-10-08T18:26:47.205Z","1.2.0":"2025-11-23T10:10:42.134Z"},"bugs":{"url":"https://github.com/BastienBYRA/CPE-Mapper/issues"},"author":{"name":"Bastien BYRA"},"license":"Apache-2.0","homepage":"https://github.com/BastienBYRA/CPE-Mapper#readme","keywords":["security","cpe","nvd","vulnerability","sbom","cyclonedx"],"repository":{"type":"git","url":"git+https://github.com/BastienBYRA/CPE-Mapper.git"},"description":"CPE-mapper is a CLI tool and JSON-based database designed to accurately map software package names to their corresponding CPEs (Common Platform Enumerations). Its main goal is to improve vulnerability identification in cases where standard package names f","maintainers":[{"name":"bastienbyra","email":"byra.bastien@gmail.com"}],"readme":"# CPE-Mapper\nCPE-mapper is a CLI tool and JSON-based database designed to accurately map software package names to their corresponding CPEs (Common Platform Enumerations). \n\nIts main goal is to improve vulnerability identification in cases where standard package names fail to match known CPEs.\n\n## Highlights\n- 📦 Easy to install and easy to use\n- ⚡ Lightweight and fast\n- 🔒 Security-focused with evidence-backed mappings\n- 🔍 Improved vulnerability detection through custom CPE mappings\n- ✨ Compatible CycloneDX JSON and SPDX JSON\n- 🧩 Roadmap includes XML support, custom user mappings database and deploying it as a server\n\n---\n\n## How does it work\nCPE-mapper is a rather simple tool.\n\nIt does not analyze your source code or repository to guess which dependencies correspond to which CPEs. Instead, it relies on a [JSON mapping file (our CPE database)](./data/cpe-mapper.json) that explicitly defines, for each package name, the corresponding CPE.\n\nWe use the [NVD (National Vulnerability Database)](https://nvd.nist.gov/) as a reference to determine which CPE is used for a specific piece of software, and we manually link them together.\n\nFor example, NVD reports vulnerabilities for Apache Tomcat using the CPE:\n```bash\ncpe:2.3:a:apache:tomcat:*:*:*:*:*:*:*:*\n```\n\nHowever, this CPE cannot be directly derived from the Java package name `org.apache.tomcat.embed:tomcat-embed-core`.\n\nTo solve this, CPE-mapper maintains a mapping in its database so that when it processes a BOM file, if it finds the package `org.apache.tomcat.embed:tomcat-embed-core`, it automatically adds the corresponding CPE `cpe:2.3:a:apache:tomcat:<your_package_version>:*:*:*:*:*:*:*` to the output.\n\n### False positives\nCPE-mapper **may report false positives**, due to how the NVD assigns CPEs to CVEs.\n\nLet’s take Log4j as an example: all CVEs related to Log4j are associated with the following CPE:\n```bash\ncpe:2.3:a:apache:log4j:<log4j_version>:*:*:*:*:*:*:*\n```\n\nThis way of tagging vulnerabilities does not take into account the different modules that make up Log4j, such as `log4j-core`, `log4j-api`, `log4j-web`, or `log4j-slf4j-impl`.\n\nIn other words, the NVD does not distinguish between the different packages that compose a piece of software; it treats the entire project as a single entity.\n\nAs a result, we decided to associate CPEs with the **core** package of each software (e.g., `log4j-core`, `tomcat-embed-core`, `logback-core`...), since these core modules are used or implemented by all their derived packages (for example in Log4j: `log4j-api`, `log4j-web`...).\n\nThis ensures that you are notified whenever a new CVE is published for the software as a whole.\n\nWhile this approach may generate false positives (for instance, some CVEs might affect a derived package you don’t actually use), it provides the safest coverage to ensure you don’t miss any relevant vulnerabilities.\n\n## Getting Started\nYou can use CPE-Mapper in your CI/CD or in your local machine.\n\n### Installing\nYou can install CPE-mapper in several ways:\n\n1. From `npm`.\n```bash\nnpm install -g @bastienbyra/cpe-mapper\n\n# You can then run it using `cpe-mapper`\n```\n\n2. Through our `Docker image`.\n```bash\ndocker run -v path/to/your/bom/folder:/data --rm ghcr.io/bastienbyra/cpe-mapper:latest apply -i /data/bom.json -o /data/mapped_bom.json\n```\n\n### Commands\n\n#### Apply\n```bash\nUsage: cpe-mapper apply [options]\n\nApply CPE mappings to a BOM file\n\nOptions:\n  -i, --input-file <file>   Input BOM file (JSON)\n  -o, --output-file <file>  Output mapped BOM file\n  -u, --no-update           Disable updating the CPE Mapping database\n  --override-cpe            Override BOM CPEs with mapped values from our database (CycloneDX only)\n  -v, --verbose             Enable verbose logging\n  -h, --help                display help for command\n```\n##### Example\nApply CPE-mapper database mappings to a BOM file\n```bash\ncpe-mapper apply -i input-bom.json -o output-bom.json\n```\n\nApply CPE-mapper database mappings to a BOM file, overwriting the existing CPEs in the input file.\n```bash\ncpe-mapper apply -i input-bom.json -o output-bom.json --override-cpe\n```\n\n> **Note**:\n>\n> The `--override-cpe` flag is intended only for CycloneDX files, as SPDX supports multiple externalRefs (and therefore multiple CPE mappings), whereas CycloneDX files can have only one\n\n#### Update\n```bash\nUsage: cpe-mapper update [options]\n\nUpdate the CPE mappings database\n\nOptions:\n  -h, --help  display help for command\n```\n\n##### Example\nCheck if the database has updates and apply them.\n```bash\ncpe-mapper update\n```\n\n### GitHub Actions\nCPE-Mapper provides a GitHub Action that can be used to apply CPE mappings to your BOM files.\n\n#### Configuration\n> **Note**: You can find the configuration in the [action.yml](./action.yml) file.\n\n```yaml\n- uses: BastienBYRA/CPE-Mapper@1.2.0\n  with:\n    # The input BOM file to which CPE-Mapper applies the mapping.\n    # Required. Example: testdata/bom.test.json\n    input-file: ''\n\n    # The name of the output BOM file.\n    # Required. Example: testdata/bom.result.json\n    output-file: ''\n\n    # Whether to override existing CPEs in the input BOM file (CycloneDX only). Choices are `true` or `false`.\n    # Optional. Default: false\n    override-cpe: false\n\n    # Enable verbose mode. Choices are `true` or `false`.\n    # Optional. Default: false\n    verbose: false\n```\n> **Tip**: It is recommended to use a release/tag version instead of main to make the workflow immutable.\n\n#### Usage\n```yaml\nname: Security CI\n\non: [push]\n\njobs:\n  apply-cpe:\n    name: Apply CPE to BOM file\n    runs-on: ubuntu-latest\n    steps:\n      - name: Apply CPE mapping\n        uses: BastienBYRA/CPE-Mapper@main\n        with:\n          input-file: testdata/bom.test.json\n          output-file: testdata/bom.result.json\n\n      # Archive the output BOM file as an artifact\n      - name: Archive artifacts\n        uses: actions/upload-artifact@v4\n        with:\n          name: mapped-sbom\n          path: testdata/bom.result.json\n          retention-days: 1\n```\n---\n\n## Contributing\nIf you would like to contribute to this project, whether by **reporting issues**, **proposing new ideas**, **developing features**, or **adding entries to the CPE database**, please see the [CONTRIBUTING](./CONTRIBUTING.md) guide for details.\n\n## Roadmap\nThe [ROADMAP](./ROADMAP.md) lists all the tasks planned for the future.","readmeFilename":"README.md"}