# ashujha301/appknox-security-scan-plugin architecture

> Architecture diagram of the GitHub repository ashujha301/appknox-security-scan-plugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashujha301/appknox-security-scan-plugin
- Repository: https://github.com/ashujha301/appknox-security-scan-plugin

## Overview

##### Project type and purpose
- This is a Jenkins plugin (Java/Maven) named Appknox Security Scan Plugin.
- It extends the Jenkins UI (via Jelly templates) to add a build step (Freestyle and Pipeline) that uploads a mobile app binary (APK/IPA) to the Appknox REST API, retrieves a static‐scan result, compares it against a “riskThreshold,” and then passes or fails the Jenkins build.

##### File structure
- pom.xml & .mvn/: standard Maven plugin packaging and build configuration.
- src/main/java/io/jenkins/plugins/AppknoxPlugin.java: the single Java class implementing the Jenkins Step/Builder extension point.
- src/main/resources/.../AppknoxPlugin/*.jelly + config.properties: UI descriptors (config fields, help HTML) for the Jenkins configuration pages.
- Jenkinsfile at repo root: CI for building/testing/releasing the plugin.
- .github/workflows/*: GitHub Actions for security scanning and release drafting.

##### README for additional insights
- The plugin requires a Jenkins “Secret Text” credential (Appknox access token).
- Users invoke it either in a Freestyle job (via “Add build step → Appknox Scan”) or in a Pipeline script (via `step([$class:'AppknoxPlugin', …])`).
- Inputs: credentialsId, filePath (workspace location of the binary), riskThreshold.

##### Main components
a. Jenkins Controller (Master)
- Hosts the plugin, manages UI, schedules build steps.
- Contains the Credentials Store.
b. Jenkins Agent (optional/executor)
- Has the workspace where the mobile binary resides.
- Runs the plugin’s “perform” or pipeline Step on behalf of the controller.
c. AppknoxPlugin (Java extension in the controller/agent process)
- Reads `credentialsId` from Credentials Store.
- Reads `filePath` pointing into the agent workspace.
- Reads `riskThreshold` parameter.
- Marshals HTTP requests and responses.
d. External Appknox REST API
- Endpoint receives binary upload, performs security scan, returns JSON with vulnerability summary and risk score.
e. Jenkins Build Job / Pipeline
- Checkout → Build App → Appknox Scan stage.
- Decision logic: compare returned risk vs. threshold → set build result (SUCCESS/FAILURE).

##### Relationships & Interactions
- User configures credentials and plugin UI in Jenkins Controller.
- On job run, the Controller schedules a build on Agent; the workspace is prepared.
- Plugin step runs on Agent, uses the Controller’s Credentials API to fetch the token.
- Plugin uploads the binary (via HTTP POST) to Appknox API.
- Appknox returns scan results (JSON).
- Plugin compares risk; pushes status back to Controller → determines overall build outcome.

##### Architectural patterns & design principles
- Jenkins plugin extension point pattern (Builder/Step).
- Separation of concerns: UI (Jelly templates) vs. logic (Java class).
- Externalized configuration via Jenkins Credentials Plugin.
- Single responsibility: the plugin only handles scan orchestration and threshold evaluation.

##### Relevant technologies
- Java 8+ (Plugin runtime)
- Maven (pom.xml)
- Jenkins Core APIs (Descriptor, Builder, Step, Credentials)
- Jelly templates for UI
- HTTP client library (bundled in Jenkins core or shaded)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Jenkins Controller"
        direction TB
        CS["Credentials Store"]:::jenkins
        JC["Jenkins Core (Build Status)"]:::jenkins
        subgraph "Plugin UI (Jelly & Properties)"
            direction TB
            UI["config.jelly"]:::plugin
            HELP1["help-credentialsId.html"]:::plugin
            HELP2["help-filepath.html"]:::plugin
            HELP3["help-riskthreshold.html"]:::plugin
            PROP["config.properties"]:::plugin
        end
        AP["AppknoxPlugin.java\n(Jenkins Builder Step)"]:::plugin
    end

    subgraph "Jenkins Agent"
        direction TB
        WS["Workspace\nMobile Binary"]:::jenkins
    end

    AN["Appknox REST API\n(Security Scan)"]:::external

    WS -.->|fetch credentials| CS
    WS -->|uploads binary| AN
    AN -->|returns JSON result| AP
    AP -->|compares risk & updates build status| JC

    subgraph "Project Files & CI"
        direction TB
        POM["pom.xml"]:::jenkins
        MVN[".mvn/"]:::jenkins
        JF["Jenkinsfile"]:::jenkins
        WF1["jenkins-security-scan.yml"]:::jenkins
        WF2["release-drafter.yml"]:::jenkins
        RD["README.md"]:::jenkins
        LIC["LICENSE.md"]:::jenkins
    end

    click AP "https://github.com/ashujha301/appknox-security-scan-plugin/blob/main/src/main/java/io/jenkins/plugins/AppknoxPlugin.java"
    click UI "https://github.com/ashujha301/appknox-security-scan-plugin/blob/main/src/main/resources/io/jenkins/plugins/AppknoxPlugin/config.jelly"
    click HELP1 "https://github.com/ashujha301/appknox-security-scan-plugin/blob/main/src/main/resources/io/jenkins/plugins/AppknoxPlugin/help-credentialsId.html"
    click HELP2 "https://github.com/ashujha301/appknox-security-scan-plugin/blob/main/src/main/resources/io/jenkins/plugins/AppknoxPlugin/help-filepath.html"
    click HELP3 "https://github.com/ashujha301/appknox-security-scan-plugin/blob/main/src/main/resources/io/jenkins/plugins/AppknoxPlugin/help-riskthreshold.html"
    click PROP "https://github.com/ashujha301/appknox-security-scan-plugin/blob/main/src/main/resources/io/jenkins/plugins/AppknoxPlugin/config.properties"
    click POM "https://github.com/ashujha301/appknox-security-scan-plugin/blob/main/pom.xml"
    click MVN "https://github.com/ashujha301/appknox-security-scan-plugin/tree/main/.mvn/"
    click JF "https://github.com/ashujha301/appknox-security-scan-plugin/tree/main/Jenkinsfile"
    click WF1 "https://github.com/ashujha301/appknox-security-scan-plugin/blob/main/.github/workflows/jenkins-security-scan.yml"
    click WF2 "https://github.com/ashujha301/appknox-security-scan-plugin/blob/main/.github/workflows/release-drafter.yml"
    click RD "https://github.com/ashujha301/appknox-security-scan-plugin/blob/main/README.md"
    click LIC "https://github.com/ashujha301/appknox-security-scan-plugin/blob/main/LICENSE.md"

    classDef jenkins fill:#D0E6FA,stroke:#2B6CB0,color:#2B6CB0;
    classDef plugin fill:#D5F5E3,stroke:#28A745,color:#1E7E34;
    classDef external fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00;
```
