Projquay 2133

modules/access-control-intro.adoc

@@ -1,6 +1,156 @@
 [[access-control-intro]]
 = Access control
 
-* Authentication providers
-* Fine-grained RBAC
-* Organizations and teams
+{productname} provides both Role Based Access Control (RBAC) and Fine-Grained Access Control, and has team features that allow for limited access control to repositories organizations and user privileges. {productname} access control features also provide support for dispersed organizations. 
+
+image:quay-tenancy-model.png[Quay tenancy model]
+
+
+== Repository organizations and users
+
+{productname} repository organizations provide a way to share repositories under a common namespace that does not belong to a single user. These organizations allow repositories to be used in a shared setting, for example, by a company. 
+
+The following is a brief overview of the organization's main page: 
+
+* **Managing teams**: Teams can be managed from the organization's main page.
+* **Creating a team**: Click the `Create Team` button on the organization main page. 
+* **Team Global Permissions**: Teams have defined global permissions in the organization. 
+* **Managing team members**: Team members can be managed by clicking on a team's name in the organization's main page. 
+* **Defined permissions**: 
++
+[cols="1,1",options="header"]
+|===
+|Permission |Abilities
+|*Members*
+|Inherits all permissions sets for the team
+
+|*Creator*
+|All member positions, plus the ability to create new repositories
+
+|*Admin*
+|Full administrative access to the organization, including the ability to create news, add members, and set permissions. 
+|===
+
+=== {productname} users
+
+A new {productname} user can set up an account at www.quay.io. Usernames must be unique, and they cannot be changed once invited to an organization. After a user account is setup, options to sign in via Google or GitHub can be added. 
+
+User accounts allow individuals to log in through the {productname} UI or a client, such as `docker login` or `podman login`. 
+
+[NOTE]
+====
+Because `docker login` via the CLI stores passwords in plaintext, we recommend generating an encrypted version of the password. 
+====
+
+Each user automatically gets their own `user namespace`, for example, quay.example.com/user/<username>. 
+
+[NOTE]
+====
+User namespaces are different from Quay organizations. There are no teams, usage logs, default permissions, or OAuth applications. By comparison, organizations are listed under quay.example.com/organization. 
+====
+
+Users who are not members of an organization can be added to the repository and given permissions. These `external` users are marked with a special character inside of the `Users and Robot Permissions` section under the `Repository Settings` tab. They are also shown under the `Collaborators View` tab on on the organization level of the `Teams and Membership` page. 
+
+=== {productname} robot accounts
+
+Robot accounts are named tokens that hold credentials for accessing external repositories. By assigning credentials to a robot, that robot can be used
+across multiple mirrored repositories that need to access the same external registry.
+
+Robot accounts are managed inside of the `Robot Accounts` tab. They can only belong to one organization, but can be assigned to multiple Teams. 
+
+[NOTE]
+====
+Teams and users can belong to multiple organizations. 
+====
+
+//should probably be an xref
+For more information on robot accounts, see link:https://access.redhat.com/documentation/en-us/red_hat_quay/3.5/html-single/manage_red_hat_quay/index#working-with-mirrored-repo[Working with mirrored repositories].
+
+=== {productname} Super users 
+
+`Super users` are a group of {productname} users with enhanced access and privileges, including: 
+
+* Super user API calls that are not visible or accessible to normal users. 
+* Access to the `Super User Admin Panel`, which allows users to
+** Change a user's email address, password, delete, or disable users.
+** Rename, delete, or take ownership of an organization. 
+** Change expiration time, rename, or delete service keys such as Clair.
+** Access to global and registry-wide usage, or audit, logs. 
+** Create and send globally visible user messages. 
+
+Primary super users are created during the initial {productname} configuration, and more can be created after configuration is complete. 
+
+[NOTE]
+====
+Super users cannot delete repositories or organizations without taking ownership of them first. 
+====
+
+== Permissions
+
+Organizations are organized into a set of Teams and can provide access to a subset of the repositories under that namespace. Permissions for users within an organization can be set for individuals, teams, and robot accounts.
+
+[NOTE]
+====
+Permissions are only applied to new users and teams when a new repository is created. 
+====
+
+=== Role Based Access Control (RBAC)
+
+{productname} offers three types of permissions: 
+
+* `Read`, which allows users, robots, and teams to pull images
+* `Write`, which allows users, robots, and teams to push images
+* `Admin`, which provides users, robots, and teams with administrative privileges
+
+[NOTE]
+====
+Administrative users can delegate new permissions for existing users and teams, change existing permissions, and revoke permissions when necessary 
+====
+
+Permissions can be delegated across the entire organization and on specific repositories. For example, `Read` permissions can be set to a specific team within the organization, while `Admin` permissions can be given to all users across all repositories within the organization.  
+
+=== Fine Grained Access Control
+
+{productname} allow users to integrate their existing identity infrastructure and use a fine-grained permissions system to map their organizational structure and grant access to whole teams to manage specific repositories. 
+
+{productname} is supported by the following authentication providers: 
+
+* Built-in Database Authentication
+* Lightweight Directory Access Protocol (LDAP) authentication and _sync
+* External OpenID Connect (OIDC) provider 
+* OpenStack Keystone 
+
+// Wondering if we could cut the following sections and refer to material already in the docs. For example, we could use the above bullet points on LDAP and link to https://access.redhat.com/documentation/en-us/red_hat_quay/3.5/html/manage_red_hat_quay/ldap-authentication-setup-for-quay-enterpriseI just copied what was in the tech deck. 
+
+==== Bind team membership to specific LDAP groups 
+
+With {productname}, team sync support can be enabled via the config application by clicking on the `Enable team synchronization support` button once  Lightweight Directory Access Protocol (LDAP) is selected as the internal authentication method:
+
+image:ldap-internal-authentication.png[LDAP authentication]
+
+The default time to sync groups is 60 minutes, but can be modified to any other time frame if needed. The first sync happens immediately after linking a team to a specific group. The last option enables any team admin, and not just super users, to sync groups. 
+
+Once {productname} is configured and restarted with the new settings, open up `org account settings` and proceed to `Teams`. Create a new team, or use an existing one, and click on `Enable Directory Synchronization` button. You will need to enter a distinguished name of the group relative to your base DN. For example: 
+
+----
+cn=quayusers,ou=cloud
+----
+
+If binding to the group goes correctly, {productname} will display the group's distinguished name and the "last updated" status on the page. 
+
+[IMPORTANT]
+====
+Once sync is enabled, adding users to the group is no longer possible. It becomes read only.
+====
+
+Users that are added to the LDAP group will automatically be added to the team as well. Robot accounts can still be added to the group directly. 
+
+==== LDAP filtering
+
+Lightweight Directory Access Protocol (LDAP) is an open, vendor neutral, industry standard application protocol for accessing and maintaining distributed directory information services over an IP network. {productname} supports using LDAP as an identity provider. {productname} users can now apply additional filters for lookup queries if (LDAP) / AD authentication is used. For information on LDAP authentication setup for {productname}, see *include link*. 
+
+==== {productname} and Red Hat SSO / Keycloak
+
+Quay Enterprise can support authentication via OpenID Connect (OIDC). Red Hat Single Sign On (SSO) is an OIDC provider that allows administrators to have a seamless authentication integration between Quay Enterprise and other application platforms such as Red Hat OpenShift Container Platform.
+
+{productname} and Red Hat SSO / Keycloak requires that TLS/SSL is properly configured to proceed with setup. Red Hat SSO supports many different types of OIDC. Quay Enterprise, however, only supports OIDC clients configured for link:https://access.redhat.com/solutions/3496181[Confidential Client Credentials]. For more information configuring Red Hat SSO, see link:https://access.redhat.com/solutions/3566061[Quay Enterprise with Red Hat Single Sign On / Keycloak].

modules/proc_deploy_quay_common_superuser.adoc

@@ -1,4 +1,4 @@
-= Quay superuser
+= {productname} superuser
 
 A `superuser` is a Quay user account that has extended privileges, including the ability to:
 

modules/security-intro.adoc

@@ -1,7 +1,144 @@
 [[security-intro]]
-= Security
+= Security Overview
 
+{productname} is built for real enterprise use cases where content governance and security are two major focus areas. {productname} content governance and security includes a built-in vulnerability scanning via Clair. 
 
-* Vulnerability scanning
-* Logging and auditing
-* Notifications and alerting
+Clair is an open source tool developed by CoreOS for Quay that generates analyses of vulnerabilities in application containers, which currently includes Open Container Initiative (OCI) and Docker images. Clients that use the Clair API to index their container images can then match their images against known vulnerabilities. 
+
+Clair supports the extraction of contents and assignment of vulnerabilities from the following official base containers: 
+
+* Ubuntu Linux
+* Debian Linux
+* Red Hat Enterprise Linux
+* SUSE
+* Oracle Linux
+* Alpine Linux
+* Amazon Linux
+* VMWare Photon
+* Python
+
+== {productname} vulnerability scanning using Clair
+
+Clair is equipped with three types of scanners, a matcher, and an updater:
+
+- **Distribution Scanner**: This scanner discovers `Distribution` information, which is typically the base operator system the layer demonstrates features of. 
+
+- **Package Scanner**: This scanner performs a package scan on the selected layer and returns all of the found packages. 
+
+- **Repository Scanner**: This scanner discovers any package repositories that are present in the layers.
+
+- **Matcher**: Matcher implementation is responsible for telling ClairCore which packages to query, how to query the security advisory database, and whether the discovered `Vulnerability` from the security advisory database affects the provided package. 
+
+- **Updater**: The updater is responsible for fetching a security advisory database and parsing the contents. 
+
+=== Understanding Clair analyses
+
+Clair analyses can be broken down into three distinct parts: 
+
+- **Indexing**: Indexing starts with submitting a `Manifest` to Clair. On receipt, Clair will fetch layers, scan their contents, and return an intermediate representation called an `IndexReport`. 
++
+Manifests are Clair's representation of a container image. Clair leverages the fact `OCI Manifests` and `Layers` are content-addressed to reduce duplicated work. 
++
+Once a `Manifest` is indexed, the `IndexReport` is persisted for later retrieval. 
+
+- **Matching**: Matching is taking an `IndexReport` and correlating vulnerabilities affecting the `Manifest` the report represents. 
++
+Clair continuously ingests new security data and a request to the matcher will always provide users with the most to date vulnerability analysis of an `IndexReport`. 
+
+- **Notifications**: Clair implements a notification service. When new vulnerabilities are discovered, the notifier service will determine if these vulnerabilities affect any indexed `Manifests`. The notifier will then take action according to its configuration.
+
+==== Notifications for vulnerabilities found by Clair
+
+{productname} 3.4 triggers different notifications for various repository events. These notifications vary based on enabled features. 
+
+[NOTE]
+====
+This include the event type `Package Vulnerability Found`
+====
+
+`Additional Filter` can be applied for `Security Level`, and there are various notification methods. Custom notification titles are also optional.  
+
+== Clair v4
+Released with {productname} 3.4, Clair v4 is the latest version of Clair. It is built on a new architecture consisting of Clair Core and a service wrapper. Clair v4  made several enhancements to Clair v2, including: 
+
+* Support for the Python programming language package. Support for additional languages is planned for future versions of Clair and {productname}.
+* Immutable data model and a new manifest-oriented API.
+* Refocus on the latest Open Container Initiative (OCI) specifications.
+* Image hashes and layer hashes are now treated as content addressable, so that images are uniquely identified as a whole. 
+
+=== Clair v4 architecture
+
+Clair v4 utilizes the ClairCore library as its engine for examining contents and reporting vulnerabilities. At a high level you can consider Clair a service wrapper to the functionality provided in the ClairCore library. 
+
+==== ClairCore 
+
+ClairCore is the engine behind Clair v4's container security solution. The ClairCore package exports our domain models, interfaces necessary to plug into our business logic, and a default set of implementations. This default set of implementations defines our support matrix. 
+
+ClairCore relies on Postgres for its persistence and the library will handle migrations if configured to do so. 
+
+The diagram below is a high level overview of ClairCore's architecture.
+
+image:clair-core-architecture.png[Connection not secure]
+
+When a `claircore.Manifest` is submitted to the LibIndex, the library will index its constituent parts and create a report with its findings. 
+
+When a `claircore.IndexReport` is provided to LibVuln, the library will discover vulnerabilities affecting it and generate a `claircore.Volunerability` report. 
+
+=== Clair v2 and Clair v4 Comparison
+
+.Clair v2 and Clair v4 component comparison
+[cols="2,1,1",options="header"]
+|===
+|Component |Clair v2 |Clair v4
+|API layers
+|In Clair v2, clients were required to provide layers to the API. 
+|Clair v4 is manifest-based, providing an easier API for users. 
+
+|Insights and reports
+|Clair v2 provided only insights on vulnerabilities
+|Clair v4 provides detailed reports on the content of the container, which can be fed to other tools for analyses or inventory purposes. 
+
+|Architecture
+|Clair v2 ran as a monolithic application. 
+|Clair v4 divides functionality across multiple services for ease of development and scaling use cases. 
+
+|Support for language packages
+|Clair v2 does not support computer language packages. 
+|Clair v4 supports Python language packages, with plans of adding more in future versions. 
+
+|Package locator
+|Clair v2 did not provide details on where packages were located inside of the container. 
+|Clair v4 identifies where packages are located inside of the container. 
+|===
+
+=== Migrating from Clair v2 to Clair v4 
+
+Starting with {productname} 3.4, Clair v4 will be used by default. It will also be the only version of Clair continually supported, as older {productname} versions are not supported with Clair v4 in production. Users should continue using Clair v2 if using a version of {productname} earlier than 3.4. 
+
+Existing {productname} 3.3 deployments will be upgraded to Clair v4 when managed via the {productname} Operator. Manually upgraded {productname} deployments can install Clair v4 side-by-side, which will cause the following:
+
+* All new image vulnerability scans to be performed by Clair v4
+* Existing images to be rescanned by Clair v4
+
+=== Clair v4 limitations
+
+The following limitations are currently being addressed by the development team: 
+
+* As of Clair v4, both operating system level and programming language packages are covered. The latter is currently limited to Python, however support for other languages will be added in the future. 
+
+* There is currently limited multi-arch support on Clair v4, which works for package managers like `rpm`, `yum`, and `dnf` that compensates for differences in endianess. 
+
+* Clair v4 does not currently support MSFT Windows images. 
+
+* Clair v4 does not currently support slim/scratch container images. 
+
+=== Air-gapped Clair v4
+
+{productname} 3.4 and Clair v4 are supported in disconnected environments. By default, Clair v4 will attempt to run automated updates against Red Hat servers. When Clair v4 in network environments is disconnected from the internet: 
+
+* The Clair v4 auto-update is disabled in the Clair `config` bundle. 
+* On a system with internet access, the vulnerability database updates is performed manually and exported to a disk. 
+* The on-disk data is then transferred to the target system with offline media. It is then manually imported. 
+
+
+