my-copy-plugin v0.1.1

Leapp is a Cross-Platform Cloud access App, built on top of Electron.

The App is designed to manage and secure Cloud Access in multi-account environments, and it is available for MacOS, Windows, and Linux.

How to build a plugin For Leapp

This README covers all the steps required to build a simple plugin for Leapp. If you are in a rush, you can jump directly to the build section!

1. Copy the template

Just click the green button above ⬆️ or use this quicklink. This action will fork the repository and gives you a ready-to-use template project for creating a new plugin.

2. Install the project locally

Just clone the forked repository and use

npm install

You are ready to go.

3. Configuring your new Plugin

Inside the project folder you will find 3 configuration file but you need to edit ony package.json:

PACKAGE.JSON overview of metadata:

{
  "name": "<YOUR-PLUGIN-NAME-IN-SNAKE-CASE>", // Must be unique on npm and can contain your organization name as well
  "author": "<YOU-OR-YOUR-ORGANIZATION>", // The author of this plugin
  "version": "1.0.0", // Any Semver Value is ok, be sure to always use a value > of the one on your npm repository
  "description": "<YOUR-AWESOME-PLUGIN-DESCRIPTION>", // Describe your plugin
  "keywords": [
    "leapp-plugin", // THIS IS MANDATORY!!!!
    "AWS" // Any other meaningful tag
    ...
  ],
  "leappPlugin": {
    "supportedOS": [
      "mac", "win", "linux" // You can insert one, two or all the values, you can also leave this tag blank to include all OSs
    ],
    "supportedSessions": [
      "awsIamRoleFederated", // Possible values are: any, aws, azure, awsIamRoleFederated, awsIamRoleChained, awsSsoRole, awsIamUser
      "awsIamRoleChained",
      "awsSsoRole"
      ...
    ]
  },
  ...
}

Remember: "keywords": [ "leapp-plugin" ] is Mandatory to allow Leapp to recognize the plugin!

4. Create your first plugin!

plugin-index.ts

Open plugin-index.ts and add a class for your plugin. plugin-index.ts is the entry point for your plugin.

E.g. export { WebConsolePlugin } from "./web-console-plugin";. We are declaring WebConsolePlugin as our plugin class.

You are done with plugin-index.ts.

plugin-class.ts (web-console-plugin.ts in our example)

Create a new typescript class and extend AwsCredentialsPlugin.

export class WebConsolePlugin extends AwsCredentialsPlugin { ... }

Note: AwsCredentialsPlugin is a class from Leapp that gives you access to temporary credentials for a given session.

Add 3 imports (usually the editor will do this step for you)

import { Session } from "@noovolari/leapp-core/models/session";
import { AwsCredentialsPlugin } from "@noovolari/leapp-core/plugin-sdk/aws-credentials-plugin";
import { PluginLogLevel } from "@noovolari/leapp-core/plugin-sdk/plugin-log-level";

Inside the class you define 2 properties and 1 method, it's as simple as that! Let's see:

get actionName(): string {
  return "Open web console"; // Friendly Name of your plugin: will be used to show the action in the Leapp Menu and Leapp plugin List
}

get actionIcon(): string {
  return "fa fa-globe"; // An icon for your plugin! Currently compatible with Font-Awesome 5+ icon tags.
}

Here you can find a list of compatible icons!

Now the main dish: the action method! Leapp will use this method to execute an action based on a session's temporary credentials set, in this case will use them to generate a link shortcut to open AWS web console for that specific session's role.

async applySessionAction(session: Session, credentials: any): Promise<void> { ... }

In this method you have access to 3 important variables:

• session Leapp session the user clicked on, or selected in the Leapp CLI.

  export class Session {
   sessionId: string;
   status: SessionStatus;
   startDateTime?: string;
   type: SessionType;
   sessionTokenExpiration: string;
  
   constructor(public sessionName: string, public region: string) {
     this.sessionId = uuid.v4();
     this.status = SessionStatus.inactive;
     this.startDateTime = undefined;
   }
  
   expired(): boolean {
     if (this.startDateTime === undefined) {
       return false;
     }
     const currentTime = new Date().getTime();
     const startTime = new Date(this.startDateTime).getTime();
     return (currentTime - startTime) / 1000 > constants.sessionDuration;
   }
  }

• credentials Credentials set for the session.

  export interface CredentialsInfo {
    sessionToken: {
      aws_access_key_id: string;
      aws_secret_access_key: string;
      aws_session_token: string;
      region: string;
    }
  }

• pluginEnvironment A set of methods to help you develop your plugin:

  • log(message: string, level: PluginLogLevel, display: boolean): void Log a custom message in Leapp or in the log file

    argument	type	description
    message	string	the message to show
    level	LogLevel	severity of the message
    display	boolean	shows the message in a toast in the desktop app when true. Otherwise, log it in the log files

  • fetch(url: string): any Retrieve the content of an URL. Returns a promise for the URL

    argument	type.	description
    url	string	a valid HTTP URL to fetch from

• openExternalUrl(url: string): void Open an external URL in the default browser

  argument	type	description
  url	string	a valid HTTP URL to open in the default browser

Finally you can find the complete code reference for our example plugin here.

Build and publish!

Build plugin.js

Use npm run build. A complete project will be created inside the root folder.

Note: you can test your plugin before submission, by copying plugin.js and package.json in a folder with the same name as your package.json name value inside ~/.Leapp/plugins/.

Publish your plugin

• Login to npm (you need to be registered on npm as a user or an organization) using npm login in the plugin folder.
• Publish the plugin with npm publish --access public.

Examples

You can find examples of plugins for Leapp in the dedicated section of our documentation.

Final notes

If you want a more detailed explanation of the plugin system please go to the dedicated section in our documentation.