Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Diataxis restructure of NVD content and added more references to link security topics #30654

Merged
merged 1 commit into from
Jan 27, 2023
Merged

Diataxis restructure of NVD content and added more references to link security topics #30654

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 43 additions & 25 deletions docs/src/main/asciidoc/security-basic-authentication-concept.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,14 @@
include::_attributes.adoc[]
:categories: security,web

HTTP Basic Authentication is one of the least resource-demanding techniques that enforce access controls to the Web resources.
It uses fields in the HTTP header and does not require HTTP cookies, session identifiers, or login pages.
HTTP Basic authentication is one of the least resource-demanding techniques that enforce access controls to web resources.
You can secure your Quarkus application endpoints with HTTP Basic authentication. Quarkus provides a built-in authentication mechanism for Basic authentication.

An HTTP user agent, such as a web browser, uses an `Authorization` header to provide a user name and password in each HTTP request.
Basic authentication uses fields in the HTTP header and does not require HTTP cookies, session identifiers, or login pages.

== Authorization header

An HTTP user agent, for example, a web browser, uses an `Authorization` header to provide a username and password in each HTTP request.
The header is specified as `Authorization: Basic <credentials>`, where credentials are the Base64 encoding of the user ID and password joined by a colon, as shown in the following example.

====
Expand All @@ -15,32 +19,46 @@ The header is specified as `Authorization: Basic <credentials>`, where credentia
If the user name is `Alice` and the password is `secret`, the HTTP authorization header would be `Authorization: Basic QWxjZTpzZWNyZXQ=`, where `QWxjZTpzZWNyZXQ=` is a Base64 encoded representation of the `Alice:secret` string.
====

The Basic Authentication mechanism does not provide confidentiality protection for the transmitted credentials.
The Basic authentication mechanism does not provide confidentiality protection for the transmitted credentials.
The credentials are merely encoded with Base64 when in transit and not encrypted or hashed in any way.
Therefore, Basic Authentication is used with HTTPS to provide confidentiality.
Therefore, Basic authentication is used with HTTPS to provide confidentiality.

Basic Authentication is a well-specified, simple challenge and response scheme that all web browsers and most web servers understand.
However, there are a few limitations associated with Basic Authentication, which include:
Basic authentication is a well-specified, simple challenge and response scheme that all web browsers and most web servers understand.

Credentials are sent as plain text::
+
--
Use HTTPS with Basic Authentication to avoid exposing the credentials.
The risk of exposing credentials as plain text increases if a load balancer terminates HTTPS, as the request is forwarded to Quarkus over HTTP.
== Limitations with using Basic authentication

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we have a rule about allowing uppercase B for basic when followed by authentication? common warning here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm on it... [we added one recently to the vale-at-red-hat repo, I will reuse that and other enhancements since the last rule update].

The following table outlines some limitations of using HTTP Basic authentication to secure your Quarkus applications:


.Limitations of HTTP Basic authentication
[cols="35%,65%"]
|===
|Limitation |Description

|Credentials are sent as plain text
|Use HTTPS with Basic authentication to avoid exposing the credentials.
The risk of exposing credentials as plain text increases if a load balancer terminates HTTPS, as the request is forwarded to Quarkus over HTTP.
Also, in multi-hop deployments, the credentials can be exposed if HTTPS is used between the client and the first Quarkus endpoint only, and the credentials are propagated to the next Quarkus endpoint over HTTP.
--

Credentials are sent with each request::
+
--
In Basic Authentication, a username and password need to be sent with each request, which increases the risk of credentials being exposed.
--

Application complexity increases::
+
--
The Quarkus application must validate that usernames, passwords, and roles are managed securely.

|Credentials are sent with each request
|In Basic authentication, a username and password need to be sent with each request, which increases the risk of credentials being exposed.

|Application complexity increases
|The Quarkus application must validate that usernames, passwords, and roles are managed securely.
This process, however, can introduce significant complexity to the application.
Depending on the use case, other authentication mechanisms that delegate username, password, and role management to specialized services might be a better choice.
--

|===

== Implementing Basic authentication in Quarkus

For more information about how you can secure your Quarkus applications by using Basic authentication, see the following resources:

* xref:security-basic-authentication-howto.adoc[Enable Basic authentication]
* xref:security-basic-authentication-tutorial.adoc[Secure a Quarkus application with Basic authentication]

== References

* xref:security-overview-concept.adoc[Quarkus Security overview]
* xref:security-authentication-mechanisms-concept.adoc#other-supported-authentication-mechanisms[Authentication mechanisms in Quarkus]

125 changes: 6 additions & 119 deletions docs/src/main/asciidoc/security-overview-concept.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Quarkus Security also supports the following features:
* <<Secret engines>>
* <<Secure serialization>>
* <<Secure auto-generated resources by REST Data with Panache>>
* <<US National Vulnerability Database registration>>
* xref:security-vulnerability-detection-concept.adoc[Security vulnerability detection and National Vulnerability Database (NVD) registration]

Quarkus Security is also highly customizable. For more information, see xref:security-customization.adoc[Security customization].

Expand Down Expand Up @@ -60,7 +60,7 @@ For more information, see xref:security-csrf-prevention.adoc[Cross-Site Request
You can add a https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite[SameSite] cookie property to any of the cookies set by a Quarkus endpoint.
For more information, see xref:http-reference.adoc#same-site-cookie[SameSite cookies].

=== Secret engines
=== Secrets engines
Secrets engines are components that store, generate, or encrypt data.

Quarkus provides comprehensive HashiCorp Vault support.
Expand All @@ -75,121 +75,8 @@ For more information, see xref:resteasy-reactive.adoc#secure-serialization[Writi

If you're using the REST Data with Panache extension to auto-generate your resources, you can still use the Security annotations within the package `javax.annotation.security`.
For more information, see xref:rest-data-panache.adoc#securing-endpoints[Securing auto-generated resources].

== Security vulnerability detection

=== US National Vulnerability Database registration

Most of the Quarkus tags are registered in the US link:https://nvd.nist.gov[National Vulnerability Database] (NVD) in Common Platform Enumeration (CPE) name format.
To view the registered Quarkus CPE names, use link:https://nvd.nist.gov/products/cpe/search/results?namingFormat=2.3&keyword=quarkus[this search query].

If the NVE database flags a CVE against a Quarkus tag, a link that provides more details about the CVE is added to the given CPE name entry.

The NVD CPE team updates the list regularly, but if you encounter a false positive, report the details by creating an issue in the link:https://github.com/quarkusio/quarkus/issues/2611[quarkusio] repository.

You can detect the vulnerabilities at the application build time with an NVD feed by using the Maven link:https://jeremylong.github.io/DependencyCheck/dependency-check-maven/[OWASP Dependency check plugin].


To add the OWASP Dependency check plugin to your Quarkus Maven project, add the following XML configuration to the `pom.xml` file:

[source,xml]
----
<plugin>
<groupId>org.owasp</groupId>
<artifactId>dependency-check-maven</artifactId>
<version>${owasp-dependency-check-plugin.version}</version>
</plugin>
----

[IMPORTANT]
====
Set the `owasp-dependency-check-plugin.version` value to `7.4.4` or later.
====

Next, configure the plugin as follows:

[source,xml]
----
<plugin>
<groupId>org.owasp</groupId>
<artifactId>dependency-check-maven</artifactId>
<version>${owasp-dependency-check-plugin.version}</version>
<configuration>
<!-- Fail only when detecting High Vulnerability issues -->
<failBuildOnCVSS>7</failBuildOnCVSS>
<suppressionFiles>
<suppressionFile>${project.basedir}/dependency-cpe-suppression.xml</suppressionFile>
</suppressionFiles>
</configuration>
</plugin>
----

To detect less severe issues, adjust the value of `failBuildOnCVSS` to suppress the false positives, as demonstrated in the following code sample:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<suppressions xmlns="https://jeremylong.github.io/DependencyCheck/dependency-suppression.1.2.xsd">
<!--
This is a CPE suppression file for the maven dependency check plugin.
Each CPE that is found by error (false positive) needs to be suppressed for a specific jar using its' GAV.
See https://jeremylong.github.io/DependencyCheck/general/suppression.html
-->
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for netty-tcnative-classes to netty
]]>
</notes>
<gav regex="true">^io\.netty:netty-tcnative-classes.*:.*$</gav>
<cpe>cpe:/a:netty:netty</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for Quarkus Mutiny to mutiny:mutiny
]]>
</notes>
<gav regex="true">^io\.quarkus:quarkus-mutiny.*:.*$</gav>
<cpe>cpe:/a:mutiny:mutiny</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for Smallrye Mutiny to mutiny:mutiny
]]>
</notes>
<gav regex="true">^io\.smallrye.reactive:mutiny.*:.*$</gav>
<cpe>cpe:/a:mutiny:mutiny</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for Smallrye Mutiny to mutiny:mutiny
]]>
</notes>
<gav regex="true">^io\.smallrye.reactive:smallrye-mutiny.*:.*$</gav>
<cpe>cpe:/a:mutiny:mutiny</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for Smallrye Mutiny to mutiny:mutiny
]]>
</notes>
<gav regex="true">^io\.smallrye.reactive:vertx-mutiny.*:.*$</gav>
<cpe>cpe:/a:mutiny:mutiny</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for graal-sdk to GraalVM (the JVM distribution)
]]>
</notes>
<gav regex="true">^org\.graalvm\.sdk:g like this
</suppress>
</suppressions>
----

Ensure that you review and update the suppression list regularly to ensure that the results are up to date.
You can optionally apply a time limit to individual suppressions by adding an expiry attribute, as outlined in the following example:

`<suppress until="2022-01-01Z">...</suppress>`
You can adjust the expiry date if you need to.
Most of the Quarkus tags are reported in the US link:https://nvd.nist.gov[National Vulnerability Database (NVD)].
For information about security vulnerabilities, see xref:security-vulnerability-detection-concept.adoc[Security vulnerability detection and reporting in Quarkus].
8 changes: 7 additions & 1 deletion docs/src/main/asciidoc/security-proactive-authentication-concept.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,4 +147,10 @@ public class AuthenticationFailedExceptionHandler {
});
}
}
----
----

== References

* xref:security-overview-concept.adoc[Quarkus Security overview]
* xref:security-authentication-mechanisms-concept.adoc#other-supported-authentication-mechanisms[Authentication mechanisms in Quarkus]

137 changes: 137 additions & 0 deletions docs/src/main/asciidoc/security-vulnerability-detection-concept.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
////
This document is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
[id="security-vulnerability-detection-concept"]
= Security vulnerability detection and reporting in Quarkus
include::_attributes.adoc[]
:categories: security,contributing

Most of the Quarkus tags are registered in the US link:https://nvd.nist.gov[National Vulnerability Database (NVD)] in Common Platform Enumeration (CPE) name format.

== US National Vulnerability Database

To view the registered Quarkus CPE names in the US NVD, use the following search URL:

https://nvd.nist.gov/products/cpe/search/results?namingFormat=2.3&keyword=quarkus

If the NVE database flags a CVE against a Quarkus tag, a link that provides more details about the CVE is added to the given CPE name entry.

The NVD CPE team updates the list regularly, but if you encounter a false positive, report the details by creating an issue in the link:https://github.com/quarkusio/quarkus/issues/2611[quarkusio] repository.

== Detecting vulnerabilities in Quarkus at build time

You can detect the vulnerabilities at the application build time with an NVD feed by using the Maven link:https://jeremylong.github.io/DependencyCheck/dependency-check-maven/[OWASP Dependency check plugin].


To add the OWASP Dependency check plugin to your Quarkus Maven project, add the following XML configuration to the `pom.xml` file:

[source,xml]
----
<plugin>
<groupId>org.owasp</groupId>
<artifactId>dependency-check-maven</artifactId>
<version>${owasp-dependency-check-plugin.version}</version>
</plugin>
----

[IMPORTANT]
====
Set the `owasp-dependency-check-plugin.version` value to `7.4.4` or later.
====

Next, configure the plugin as follows:

[source,xml]
----
<plugin>
<groupId>org.owasp</groupId>
<artifactId>dependency-check-maven</artifactId>
<version>${owasp-dependency-check-plugin.version}</version>
<configuration>
<!-- Fail only when detecting High Vulnerability issues -->
<failBuildOnCVSS>7</failBuildOnCVSS>
<suppressionFiles>
<suppressionFile>${project.basedir}/dependency-cpe-suppression.xml</suppressionFile>
</suppressionFiles>
</configuration>
</plugin>
----

To detect less severe issues, adjust the value of `failBuildOnCVSS` to suppress the false positives, as demonstrated in the following code sample:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<suppressions xmlns="https://jeremylong.github.io/DependencyCheck/dependency-suppression.1.2.xsd">
<!--
This is a CPE suppression file for the maven dependency check plugin.
Each CPE that is found by error (false positive) needs to be suppressed for a specific jar using its' GAV.
See https://jeremylong.github.io/DependencyCheck/general/suppression.html
-->
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for netty-tcnative-classes to netty
]]>
</notes>
<gav regex="true">^io\.netty:netty-tcnative-classes.*:.*$</gav>
<cpe>cpe:/a:netty:netty</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for Quarkus Mutiny to mutiny:mutiny
]]>
</notes>
<gav regex="true">^io\.quarkus:quarkus-mutiny.*:.*$</gav>
<cpe>cpe:/a:mutiny:mutiny</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for Smallrye Mutiny to mutiny:mutiny
]]>
</notes>
<gav regex="true">^io\.smallrye.reactive:mutiny.*:.*$</gav>
<cpe>cpe:/a:mutiny:mutiny</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for Smallrye Mutiny to mutiny:mutiny
]]>
</notes>
<gav regex="true">^io\.smallrye.reactive:smallrye-mutiny.*:.*$</gav>
<cpe>cpe:/a:mutiny:mutiny</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for Smallrye Mutiny to mutiny:mutiny
]]>
</notes>
<gav regex="true">^io\.smallrye.reactive:vertx-mutiny.*:.*$</gav>
<cpe>cpe:/a:mutiny:mutiny</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for graal-sdk to GraalVM (the JVM distribution)
]]>
</notes>
<gav regex="true">^org\.graalvm\.sdk:g like this
</suppress>
</suppressions>
----

Ensure that you review and update the suppression list regularly to ensure that the results are up to date.
You can optionally apply a time limit to individual suppressions by adding an expiry attribute, as outlined in the following example:

`<suppress until="2022-01-01Z">...</suppress>`
You can adjust the expiry date if you need to.

== References

* xref:security-overview-concept.adoc[Quarkus Security overview]
* xref:security-authentication-mechanisms-concept.adoc#other-supported-authentication-mechanisms[Authentication mechanisms in Quarkus]