Normalize permission model

[nscuro]

Current Behavior

Currently, the PERMISSION table is very simplistic:

erDiagram
    PERMISSION {
        BIGINT ID PK
        TEXT NAME
        TEXT DESCRIPTION
    }

Loading

Available permissions are defined in the Permissions class.

Proposed Behavior

Normalize the permission model, such that subject and verb are separated:

erDiagram
    PERMISSION {
        BIGINT ID PK
        TEXT SUBJECT
        TEXT VERB
    }

Loading

The following legacy permissions:

• PORTFOLIO_MANAGEMENT
• PORTFOLIO_MANAGEMENT_CREATE
• PORTFOLIO_MANAGEMENT_READ
• PORTFOLIO_MANAGEMENT_UPDATE
• PORTFOLIO_MANAGEMENT_DELETE

Would translate to:

SUBJECT	VERB
PORTFOLIO	ALL
PORTFOLIO	CREATE
PORTFOLIO	READ
PORTFOLIO	UPDATE
PORTFOLIO	DELETE

We could further assign ranks to each verb, such that UPDATE implies READ, and ALL implies all verbs. This could be achieved by defining verbs in an enum, or a separate VERB table.

With the above in place, queries could use efficient "has at least verb X on subject Y" predicates. This roughly resembles GitLab's model of "access levels" (see DependencyTrack/hyades#1632 (comment)).

Checklist

• I have read and understand the contributing guidelines
• I have checked the existing issues for whether this enhancement was already requested

[nscuro]

Blocked by DependencyTrack/hyades#1758

This needs adjustments in Alpine, and we cannot do them while still having to support DT v4.

[jhoward-lm]

This needs adjustments in Alpine, and we cannot do them while still having to support DT v4.

To achieve this, what do you think about a pattern that allows downstream projects to supply their own "resource" definitions enum? Something like the following, or an SPI maybe? I believe it's in alignment with what the issue description states and might allow for a little bit of flexibility if carefully coordinated between the two projects.

Haven't tested it out or anything, but just as an example:

Alpine Permission

@PersistenceCapable
@JsonInclude(JsonInclude.Include.NON_NULL)
public class Permission <E extends Enum<E>> implements Serializable {

    private static final long serialVersionUID = 1420020753285692448L;

    public static enum AccessLevel {
        CREATE,
        READ,
        UPDATE,
        DELETE,
        ALL
    }

    public Permission(E resource, AccessLevel accessLevel, String description) {
        this.resource = resource;
        this.accessLevel = accessLevel;
        this.description = description;
    }

    @PrimaryKey
    @Persistent(valueStrategy = IdGeneratorStrategy.NATIVE)
    @JsonIgnore
    private long id;

    @Persistent
    @Column(name = "RESOURCE", allowsNull = "false", jdbcType = "VARCHAR")
    @NotBlank
    E resource;

    @Persistent
    @Column(name = "ACCESS_LEVEL", allowsNull = "false", jdbcType = "VARCHAR")
    @NotBlank
    AccessLevel accessLevel;

    // ...

    @Override
    public String toString() {
        return "%s_%s".formatted(resource.name(), accessLevel.name());
    }

}

then in dependency-track/hyades-apiserver, Permissions might look something like

hyades-apiserver Permissions

// PermissionResources.java
public enum PermissionResources {
    BOM,
    PORTFOLIO,
    VULNERABILITY,
    POLICY,
    // ...
}

// Permissions.java
import alpine.model.Permission;

public class Permissions extends Permission<PermissionResources> {

    public Permissions(PermissionResources resource, Permission.AccessLevel accessLevel, String description) {
        super(resource, accessLevel, description);
    }

}

// usage example
new Permissions(PermissionResources.BOM, Permission.AccessLevel.CREATE,
        "Allows the ability to upload CycloneDX Software Bill of Materials (SBOM)"),
new Permissions(PermissionResources.PORTFOLIO, Permission.AccessLevel.READ,
        "Provides the ability to view the portfolio of projects, components, and licenses"),
// ...

[nscuro]

@jhoward-lm Would need to try this out because I'm not sure how well generics and inheritance work with DataNucleus here. The generic type parameter for the enum would probably work, mostly unsure about the inheritance part.

[jhoward-lm]

@nscuro Here's a working example; I just threw everything into hyades-apiserver under org.dependencytrack.model because it was easier to manage.

A few highlights:

• PermissionGeneric is just a placeholder name to avoid collision with Permission, same with PermissionsImpl and Permissions
• the base PermissionGeneric class is abstract and annotated with

  @Inheritance(strategy = InheritanceStrategy.SUBCLASS_TABLE)

• the PermissionResources are probably wrong; just sample data

PermissionGeneric.java

package org.dependencytrack.model;

// imports

@PersistenceCapable
@Inheritance(strategy = InheritanceStrategy.SUBCLASS_TABLE)
@JsonInclude(JsonInclude.Include.NON_NULL)
public abstract class PermissionGeneric<E extends Enum<E>> implements Serializable {

    private static final long serialVersionUID = 1420020753285692448L;

    public static enum AccessLevel {
        CREATE,
        READ,
        UPDATE,
        DELETE,
        ALL
    }

    public PermissionGeneric(E resource, AccessLevel accessLevel, String description) {
        this.resource = resource;
        this.accessLevel = accessLevel;
        this.description = description;
    }

    @PrimaryKey
    @Persistent(valueStrategy = IdGeneratorStrategy.NATIVE)
    @JsonIgnore
    private long id;

    @Persistent
    @Column(name = "RESOURCE", allowsNull = "false", jdbcType = "VARCHAR")
    @NotBlank
    E resource;

    @Persistent
    @Column(name = "ACCESS_LEVEL", allowsNull = "false", jdbcType = "VARCHAR")
    @NotBlank
    AccessLevel accessLevel;

    @Persistent
    @Column(name = "DESCRIPTION", jdbcType = "CLOB")
    private String description;

    // teams/users fields

    // getters/setters

    @Override
    public String toString() {
        return "%s_%s".formatted(resource.name(), accessLevel.name());
    }

}

PermissionResources.java

package org.dependencytrack.model;

public enum PermissionResources {

    ACCESS_MANAGEMENT,
    BADGES,
    BOM,
    POLICY_MANAGEMENT,
    POLICY_VIOLATION,
    POLICY_VIOLATION_ANALYSIS,
    PORTFOLIO,
    PORTFOLIO_MANAGEMENT,
    PROJECT,
    ROLE_MANAGEMENT,
    SYSTEM_CONFIGURATION,
    TAG_MANAGEMENT,
    VULNERABILITY,
    VULNERABILITY_ANALYSIS,
    VULNERABILITY_MANAGEMENT

}

PermissionsImpl.java

package org.dependencytrack.model;

import javax.jdo.annotations.PersistenceCapable;

@PersistenceCapable(table = "PERMISSIONS_IMPL")
public class PermissionsImpl extends PermissionGeneric<PermissionResources> {

    public PermissionsImpl(PermissionResources resource, PermissionGeneric.AccessLevel accessLevel,
            String description) {
        super(resource, accessLevel, description);
    }

}

persistence.xml

<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd" version="3.0">
  <persistence-unit name="Alpine">
    <!-- ... -->
    <class>org.dependencytrack.model.PermissionGeneric</class>
    <class>org.dependencytrack.model.PermissionsImpl</class>
    <exclude-unlisted-classes>true</exclude-unlisted-classes>
    <shared-cache-mode>NONE</shared-cache-mode>
  </persistence-unit>
</persistence>

changeSet

<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<databaseChangeLog
        objectQuotingStrategy="QUOTE_ALL_OBJECTS"
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
            http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

    <changeSet id="v5.6.0-permissions" author="jhoward-lm">
        <createTable ifNotExists="true" tableName="PERMISSIONS_IMPL">
            <column autoIncrement="true" name="ID" type="BIGINT">
                <constraints nullable="false" primaryKey="true" primaryKeyName="PERMISSIONS_IMPL_PK" />
            </column>

            <column name="RESOURCE" type="VARCHAR(255)">
                <constraints nullable="false" validateNullable="true" />
            </column>

            <column name="ACCESS_LEVEL" type="VARCHAR(255)">
                <constraints nullable="false" validateNullable="true" />
            </column>

            <column name="DESCRIPTION" type="TEXT" />
        </createTable>

        <createIndex unique="true" tableName="PERMISSIONS_IMPL" indexName="PERMISSIONS_IMPL_COMPOSITE_IDX">
            <column name="RESOURCE" />
            <column name="ACCESS_LEVEL" />
        </createIndex>
    </changeSet>
</databaseChangeLog>

DefaultObjectGenerator.java scratch code

    /**
     * Loads the default permissions
     */
    private void loadDefaultPermissions(final QueryManager qm) {
        // ...

        for (final PermissionResources value : PermissionResources.values()) {
            for (final PermissionGeneric.AccessLevel accessLevel : PermissionGeneric.AccessLevel.values()) {
                var permission = new PermissionsImpl(value, accessLevel, "");
                LOGGER.info("Creating permission: " + permission.toString());
                qm.persist(permission);
            }
        }
    }

SELECT * FROM "PERMISSIONS_IMPL" after init tasks run

ID	RESOURCE	ACCESS_LEVEL	DESCRIPTION
1	ACCESS_MANAGEMENT	CREATE
2	ACCESS_MANAGEMENT	READ
3	ACCESS_MANAGEMENT	UPDATE
4	ACCESS_MANAGEMENT	DELETE
5	ACCESS_MANAGEMENT	ALL
6	BADGES	CREATE
7	BADGES	READ
8	BADGES	UPDATE
9	BADGES	DELETE
10	BADGES	ALL
11	BOM	CREATE
12	BOM	READ
13	BOM	UPDATE
14	BOM	DELETE
15	BOM	ALL
16	POLICY_MANAGEMENT	CREATE
17	POLICY_MANAGEMENT	READ
18	POLICY_MANAGEMENT	UPDATE
19	POLICY_MANAGEMENT	DELETE
20	POLICY_MANAGEMENT	ALL
21	POLICY_VIOLATION	CREATE
22	POLICY_VIOLATION	READ
23	POLICY_VIOLATION	UPDATE
24	POLICY_VIOLATION	DELETE
25	POLICY_VIOLATION	ALL
26	POLICY_VIOLATION_ANALYSIS	CREATE
27	POLICY_VIOLATION_ANALYSIS	READ
28	POLICY_VIOLATION_ANALYSIS	UPDATE
29	POLICY_VIOLATION_ANALYSIS	DELETE
30	POLICY_VIOLATION_ANALYSIS	ALL
31	PORTFOLIO	CREATE
32	PORTFOLIO	READ
33	PORTFOLIO	UPDATE
34	PORTFOLIO	DELETE
35	PORTFOLIO	ALL
36	PORTFOLIO_MANAGEMENT	CREATE
37	PORTFOLIO_MANAGEMENT	READ
38	PORTFOLIO_MANAGEMENT	UPDATE
39	PORTFOLIO_MANAGEMENT	DELETE
40	PORTFOLIO_MANAGEMENT	ALL
41	PROJECT	CREATE
42	PROJECT	READ
43	PROJECT	UPDATE
44	PROJECT	DELETE
45	PROJECT	ALL
46	ROLE_MANAGEMENT	CREATE
47	ROLE_MANAGEMENT	READ
48	ROLE_MANAGEMENT	UPDATE
49	ROLE_MANAGEMENT	DELETE
50	ROLE_MANAGEMENT	ALL

[jhoward-lm]

On a somewhat related note, a similar inheritance pattern could be applied to the 3 user models (minus the use of generics).

Using InheritanceStrategy.SUPERCLASS_TABLE with a discriminator column could theoretically consolidate them into a single table

[nscuro]

Using InheritanceStrategy.SUPERCLASS_TABLE with a discriminator column could theoretically consolidate them into a single table

Oh nice, that sounds promising!

[jhoward-lm]

Oh nice, that sounds promising!

@nscuro Here's a gist with a rough example of that if you're interested. If you end up creating an issue for consolidating user tables it can be linked there as well

[nscuro]

Awesome thanks!

If you end up creating an issue for consolidating user tables [...]

Already did: DependencyTrack/hyades#1760

I had also raised an ADR PR which I am happy to update with your suggestions tomorrow: DependencyTrack/hyades#1764

[nscuro]

@jhoward-lm Added the gist (lol) of your Gist, and a link to the full Gist to the ADR in DependencyTrack/hyades#1764.

[nscuro]

@jhoward-lm Here's a working example;

Just gave this a spin, and while it works I wonder if it wouldn't be simpler to just keep resource as String instead.

Code that doesn't have knowledge about PermissionsImpl would have to query for PermissionGeneric instead, e.g.:

final List<PermissionGeneric> permissions = 
                qm.getPersistenceManager().newQuery(PermissionGeneric.class).executeList();

In this case the generic type parameter is not available, so you end up with an opaque Enum / Enum<?> for resource.

Granted, one could still do simple enum comparisons like this:

var hasPermission = permissions.getFirst().resource == PermissionResources.ACCESS_MANAGEMENT;

But you lose the convenience of the compiler knowing that resource is of type PermissionResources. Meaning the following would also compile:

var hasPermission = permissions.getFirst().resource == Severity.CRITICAL;

The same limitation would apply to relationships in Alpine code, such as TEAMS_PERMISSIONS. Team would have to model it's relationship with PermissionGeneric, again missing out on compiler assistance for resource.

We can still model resource as enum in the database, but for the Java side of things, I believe a String would keep things simpler. WDYT?