Patch release v2.2.3 for recent security fixes

[JanWesterkamp-iJUG]

Thank you for taking your time to talk with us!

What is this issue about?

• Bug report
• Feature request
• Question

Description
Is it possible to cut a patch release (like v2.2.3), that contains the already merged recent security fixes from dependencies?

Especially the following should be covered:

• Bump netty-codec-http to latest v4.1.87.Final Bump netty-codec-http to latest v4.1.87.Final #612
• Bump netty-codec-http to latest v4.1.89.Final Bump netty-codec-http to latest v4.1.89.Final #615

Other patch level updates (and optionally feature enhancements, but no breaking changes) might be included too.

It looks like the plugin is heading for a major release, but we are using it for the generation of specification documents in Jakarta EE and MicroProfile a lot and need to fix it with patch level releases there - so a new major version will break Semantic Versioning then, especially when there are break changes included, that affect us.

Details can be found in these vulnerability reports:

• https://bugs.eclipse.org/bugs/show_bug.cgi?id=581579
• https://bugs.eclipse.org/bugs/show_bug.cgi?id=581580

Meanwhile, I created a workaround PR for the asciidoc-asciidoctor-maven-examples:

• Workaround for netty-codec-http security issues asciidoctor-maven-examples#181
• Deviating parent versions fixed asciidoctor-maven-examples#182 (optional fix)

I can refactor that back, when a patched plugin version is released.

Environment information

• asciidoctor-maven-plugin version: >2.2.2
• asciidoctorj version: 2.5.7

• Maven, Java and OS version: ___

[abelsromero]

Is it possible to cut a patch release (like v2.2.3),

Could be done. We can just create a new branch from the last tag and port ONLY the required fixes there. Netty + CI stuff probably. Can you confirm the only requirement is netty please?

But keep in mind netty is used for the preview features of the plugin to publish the converted docs in a local server. Nothing to do with the actual conversion process. I can imagine some CVE scanner flagging the plugin, but in a normal CI pipeline netty is not used at all.

It looks like the plugin is heading for a major release, but we are using it for the generation of specification documents in Jakarta EE and MicroProfile a lot and need to fix it with patch level releases there - so a new major version will break Semantic Versioning then, especially when there are break changes included, that affect us.

I understand it's important to keep the build clean of security alerts, but I don't see how the plugin version affects the release. Users don't see the plugins used during the build, especially for docs right?
On the breaking changes, the main thing is that the maven-site modules have been split into actual maven sub-modules. If you don't use it, the only change is removing support for AsciidoctorJ 1.6.x. The repo contains migration guides plugin v3 migration guide & site module migration guide

[JanWesterkamp-iJUG]

Ok, i will have a look at the migration guide. On the other hand, I had some things in mind that should go into the next major release and I don't want to wait for 4.0.0... ;-)

For the Patch Release, this would be very nice: You are right, in most cases the document generation is an internal thing, but in MicroProfile it's differnt. There we have the MicroProfile Parent project, which defines the default build config to be used in MicroProfile component specs. So, there it is the parent dependency to them and versioning should follow the Semantic Versioning conventions.
For details, you can have a look on these sides:
jakartaee/platform#607 (in the current version page 46 to 50)

I can create a wish list for the patch release, as the version overwrites sometimes can confuse people - so if we have a chance to get current defaults, usage would be simpler.

Yes, the security scanners might be the most significant reason for patching this, in the current MP Parent there are more open issues, that could not make it into the last release (3.0) in time - but the MP 6.0 umbrella spec covers them already (except the last two).

[abelsromero]

I had some things in mind that should go into the next major release and I don't want to wait for 4.0.0... ;-)

Just create the issues, no one is in a hurry for v3, and we could add more stuff.
By design, the plugin is a thin layer on top of AsciidoctorJ + jRuby. And users can override AsciidoctorJ and jRuby to use the latest, that's why there's not much of a hurry to release.

[abelsromero]

I reviewed the commits and we'd need to port the following changes. Nothing risky or too complicated.

• Bump Doxia to v1.11.1 & maven-site-plugin IT to v3.12.0
• Bump test dependencies
• Fix absolute to relative path (docs)
• Proofread documentation
• Bump build related Maven plugins
• Fixes conversion failure when using erb template
• Bump Asciidoctorj to latest v.x.x.x
• Bump netty-codec-http to latest v.x.x.x

Other TODOs

• Find out how to make a release not from main branch 🤔 worst case scenario I replace main temporarily
• Update reference to docs in https://github.com/asciidoctor/docs.asciidoctor.org

[abelsromero]

Made a test branch with quick-dirty changes and everything is fine https://github.com/asciidoctor/asciidoctor-maven-plugin/tree/v2.2.3-fix-release.
I will proceed now to do it correctly on the v2.2.x branch for the proper release during the weak.

[JanWesterkamp-iJUG]

Thanks a lot so far!

Adding to your list, I would suggest the following versions:

• netty-codec-http v4.1.89
• Asciidoctorj v2.5.7
• jRuby v9.3.8.0

I am a little bit unsure regarding the following changes, that might require further research:

• Set minimal maven version to 3.8.5 #607 Changing the minimum Maven version would be a breaking change, but there is a severe Maven issue with the older versions.
• Bump Doxia to v1.11.1 & maven-site-plugin IT to v3.12.0 #579 Doxia and Maven Site Plugin - these are minor updates, but fixes? And there is an open issue with the commons.io dependency (https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-29425), but this is fixed in a 2.0.0 Milestone release only.

BTW:
The it looks like the Enforcer Plugin config is still pointing to a different, old version of Maven at least in the root pom.xml:

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-enforcer-plugin</artifactId>
                <version>3.1.0</version>
                <executions>
                    <execution>
                        <id>enforce-maven</id>
                        <goals>
                            <goal>enforce</goal>
                        </goals>
                        <configuration>
                            <rules>
                                <requireMavenVersion>
                                    <version>3.0.5</version>
                                </requireMavenVersion>
                            </rules>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

[abelsromero]

Thanks for the feedback!

Adding to your list, I would suggest the following versions:

* netty-codec-http v4.1.89

* Asciidoctorj v2.5.7

* jRuby v9.3.8.0

Check! ✅ The branch uses netty 4.1.90.Final instead of 4.1.89. Is that an issue?

• Set minimal maven version to 3.8.5 #607

That's not going in, and it should not be an issue. The minimal version will still be 3.0.5 as the other 2.x versions, but it's a formality, in practice, it doesn't change anything thanks to how super-stable Maven APIs are. No one ever reported the plugin not working on v3.x maven cli.

• Bump Doxia to v1.11.1 & maven-site-plugin IT to v3.12.0 #579

These are minor (in semantic versioning sense) bumps to keep main and 2.2.3-fix branch aligned. If you are not using the maven-site integration, and even in that scenario, versions should be compatible. They only do major changes in major versions.
Same as with the enforcer, I am not pushing all build dependencies to the absolute latest to keep main and 2.2.3 branches aligned. Unless you tell me the contrary, I consider that a nice to have that will depend on my available time the next days. If I have some extra time I'd like to bump all plugins (compiler, javadoc, etc.) in both main and 2.2.3-fix branches. If I can't I'd leave as it is.

TLDR; I understand we are all set, I will see to leave the branch clean tomorrow and Saturday I can release. What scanner are you using? I am familiar with trivy and grype and I can do a run myself.

[JanWesterkamp-iJUG]

Thanks for the feedback!

Adding to your list, I would suggest the following versions:

* netty-codec-http v4.1.89

* Asciidoctorj v2.5.7

* jRuby v9.3.8.0

Check! ✅ The branch uses netty 4.1.90.Final instead of 4.1.89. Is that an issue?

That's perfect!

• Set minimal maven version to 3.8.5 #607

That's not going in, and it should not be an issue. The minimal version will still be 3.0.5 as the other 2.x versions, but it's a formality, in practice, it doesn't change anything thanks to how super-stable Maven APIs are. No one ever reported the plugin not working on v3.x maven cli.

I am fine with this - even when the Enforcer Plugin prevents execution with lower Maven versions, the attack can be successful before - this only would force somebody to update and breakes things.

• Bump Doxia to v1.11.1 & maven-site-plugin IT to v3.12.0 #579

These are minor (in semantic versioning sense) bumps to keep main and 2.2.3-fix branch aligned. If you are not using the maven-site integration, and even in that scenario, versions should be compatible. They only do major changes in major versions. Same as with the enforcer, I am not pushing all build dependencies to the absolute latest to keep main and 2.2.3 branches aligned. Unless you tell me the contrary, I consider that a nice to have that will depend on my available time the next days. If I have some extra time I'd like to bump all plugins (compiler, javadoc, etc.) in both main and 2.2.3-fix branches. If I can't I'd leave as it is.

TLDR; I understand we are all set, I will see to leave the branch clean tomorrow and Saturday I can release. What scanner are you using? I am familiar with trivy and grype and I can do a run myself.

I am not scannin b myself at the moment - I use the results shown on https//mvnrepository.com, but I plan to set up a GitLab instance and start with the default set of scanners and used Clair in the past.

Thanks a lot, I will be in the JavaLand next week, but may be can do some patches in between, when a patch release is available. If it takes some additional days, it's not a problem too.

[abelsromero]

Release "done", files should be available soon, on our side just need to document the GH release done 👉 https://github.com/asciidoctor/asciidoctor-maven-plugin/releases.

Interesting the new report Sonatype sends you in an email
https://sbom.lift.sonatype.com/report/T1-a0368c8f29fdaa555824-2154970bb9bb28-1679166487-a5b0487432e74ab896f6640f4f1717ae

The High vulnerabilities are because the plugin still uses Maven 3.0.x dependencies, but in a real scenario uses, whatever Maven is in the machine or Maven wrapper in the consuming project.

[abelsromero]

It's available already 🎉 https://central.sonatype.com/artifact/org.asciidoctor/asciidoctor-maven-plugin/2.2.3

I am closing this issue as completed, but please do let us know if there's anything else.