Sitelet https://github.com/serj/JCapsLock/tree/main/docs
Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 
caveats.md
caveats.md
 
 

README.md

JCapsLock Usage Guide

Quick Start

After installing the plugin to your local repository (mvn install), you can use the simplified commands:

Basic Usage

# Simple analysis with default settings
mvn capslock:analyze

# Analyze with all features enabled
mvn capslock:analyze -Dcapslock.includeTest=true -Dcapslock.showTree=true -Dcapslock.fetchOptionalMetadata=true

Command Shortcuts

The plugin prefix capslock allows you to use short commands instead of the full plugin coordinates:

Short Command Full Command
mvn capslock:analyze mvn com.github.serj:mvn-capslock:1.0-SNAPSHOT:analyze

Optional Dependencies Analysis

JCapsLock can analyze optional dependencies that projects declare but don't automatically include:

1. Include Optional Dependencies (Default: true)

# Analyze optional dependencies in the dependency tree
mvn capslock:analyze -Dcapslock.includeOptional=true

2. Fetch Optional Metadata

# Discover and analyze optional dependencies from POM files
# This finds optional dependencies not in your dependency tree
mvn capslock:analyze -Dcapslock.fetchOptionalMetadata=true

Common Use Cases

Full Analysis with All Features

mvn capslock:analyze \
  -Dcapslock.includeTest=true \
  -Dcapslock.includeOptional=true \
  -Dcapslock.fetchOptionalMetadata=true \
  -Dcapslock.showTree=true \
  -Dcapslock.verbose=true

Analyze Specific Package

mvn capslock:analyze -Dcapslock.package=org.apache.commons:commons-compress

Generate JSON Report

mvn capslock:analyze \
  -Dcapslock.format=json \
  -Dcapslock.outputFile=capabilities.json

Security Audit Mode

# Show all capabilities including test and optional dependencies
mvn capslock:analyze \
  -Dcapslock.includeTest=true \
  -Dcapslock.fetchOptionalMetadata=true \
  -Dcapslock.verbose=true \
  -Dcapslock.outputFile=security-audit.txt

Configuration Parameters

Parameter Property Default Description
format capslock.format text Output format: text, json, sarif
verbose capslock.verbose false Show detailed capability usage
includeSafe capslock.includeSafe false Include CAPABILITY_SAFE in output
includeOptional capslock.includeOptional true Analyze optional dependencies
includeTest capslock.includeTest false Analyze test scope dependencies
fetchOptionalMetadata capslock.fetchOptionalMetadata false Discover optional deps from POMs
showTree capslock.showTree true Display dependency tree structure
package capslock.package - Specific package to analyze
outputFile capslock.outputFile - Output file path
skip capslock.skip false Skip analysis

Optional Dependencies Explained

What are Optional Dependencies?

Optional dependencies are dependencies that a library declares as "optional" in its POM. They are not automatically included in your project but may be needed for certain features.

Why Analyze Optional Dependencies?

  • Security: Optional dependencies might be pulled in at runtime
  • Compliance: Need to know all possible capabilities
  • Feature Discovery: Understand what capabilities are available with optional features

Example

If a library has optional compression support:

<dependency>
  <groupId>org.apache.commons</groupId>
  <artifactId>commons-compress</artifactId>
  <optional>true</optional>
</dependency>

With fetchOptionalMetadata=true, JCapsLock will:

  1. Detect this optional dependency from the POM
  2. Analyze its capabilities
  3. Mark them as "optional" in the report

Tips

  1. First Run: Start with basic mvn capslock:analyze to see direct dependencies
  2. Deep Dive: Add -Dcapslock.fetchOptionalMetadata=true to discover optional capabilities
  3. CI/CD: Use -Dcapslock.format=sarif for integration with security tools
  4. Debugging: Use -Dcapslock.verbose=true to see detailed call chains