Skip to content

About

New API of Shevery that faster than Shizuku API

Resources

Stars

7 stars

Watchers

1 watching

Forks

Repository files navigation

Shevery-API

Shevery-API is the official, low-latency Privilege API for Shevery. It provides direct access to privileged Binder transactions, one-shot bounded shell execution (execFast), UserService processes, interactive rish PTY sessions, and system properties under ADB (UID 2000) or Root (UID 0) without relying on the legacy Shizuku API_V23 permission stack.

Architecture & Permission Separation

Channel Permission Owner Package Provider Authority
Shevery Native API com.hamondev.shevery.permission.PRIVILEGED_API com.hamondev.shevery ${applicationId}.shevery
Shizuku Legacy Stub moe.shizuku.manager.permission.API_V23 moe.shizuku.privileged.api (Stub) ${applicationId}.shizuku

Key Capabilities & Hardening

  • Fast-Pull Binder Acquisition (SheveryPrivilege.connectFast(context)): Unlike legacy Shizuku clients that passively wait for IActivityManager process/UID observers and retry backoffs, SheveryProvider and SheveryPrivilege.connectFast(context) pull the active server binder directly from content://com.hamondev.shevery.shevery (METHOD_REQUEST_BINDER) in a single IPC call on startup.
  • Zero-Stub Raw Parcel Codec (LegacyParcelCodec): Inspects raw BUNDLE_MAGIC_NATIVE (0x4C444E42) parcel bytes (including Android 13+ lazy parcelables) before BaseBundle.unparcel() is triggered, preventing ClassNotFoundException / BadParcelableException across isolated classloaders.
  • One-Shot Fast Execution (SheveryPrivilege.execFast): Executes short-lived commands over a single flat Parcel transaction (BINDER_TRANSACTION_execFast) with bounded output (256 KB max per stream) and configurable timeout (30s default) without spawning 3 separate ParcelFileDescriptor pipe transfer threads.
  • Fine-Grained Capability Bitmasks (CAP_*): Supports per-capability enforcement and inspection (CAP_SHELL_EXEC, CAP_BINDER_PROXY, CAP_USER_SERVICE, CAP_SYSTEM_PROPS).
  • Hardened Server & IPC Security:
    • Direct Process Execution: Executes command arrays directly via Runtime.exec(cmd, env, dir) without shell interpolation (sh -c) or command-line concatenation.
    • Self-Binder Privilege Escalation Guard: Rejects transactRemote calls targeting local Binder instances of the server process itself so normal granted clients cannot invoke manager-only endpoints after Binder.clearCallingIdentity().
    • Untrusted Bundle Confinement: Confines incoming server Bundle arguments to the framework ClassLoader (Bundle.class.getClassLoader()) prior to unparceling.
    • Multi-User UserService Isolation & JNI Abort Protection: Keys UserServiceRecord entries by userId:packageName:tagOrClass, caches interfaceDescriptor on binder attach to avoid synchronous round-trips or writeInterfaceToken(null) JNI aborts during destroy(), and initializes ActivityThread$AppBindData prior to LoadedApk.makeApplication().
    • Hardened rish PTY Lifecycle: Fixes stderr pipe descriptor routing, closes PTY master descriptors (ptmx) on process exit, detaches native transfer pthreads (pthread_detach), monitors output pipe reader loss via poll(), terminates child process groups cleanly via waitid + kill(-pid, SIGKILL), and reaps uncollected exited hosts.

Integration Guide

1. Gradle Dependencies

Add the Shevery-API Maven repository in settings.gradle (or settings.gradle.kts):

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://raw.githubusercontent.com/HmnDev-Tech/Shevery-API/maven") }
    }
}

Then add the dependencies in your module's build.gradle (or build.gradle.kts):

dependencies {
    implementation "com.hamondev.shevery.api:api:14.6.5"
    implementation "com.hamondev.shevery.api:provider:14.6.5"
}

2. Register SheveryProvider in AndroidManifest.xml

<uses-permission android:name="com.hamondev.shevery.permission.PRIVILEGED_API" />

<application>
    <provider
        android:name="com.hamondev.shevery.api.SheveryProvider"
        android:authorities="${applicationId}.shevery"
        android:multiprocess="false"
        android:enabled="true"
        android:exported="true" />
</application>

3. Acquire Binder, Check Capabilities & Execute Commands

import android.content.pm.PackageManager;
import com.hamondev.shevery.api.SheveryApiConstants;
import com.hamondev.shevery.api.SheveryPrivilege;

public class MainActivity extends Activity {

    private static final int REQ_CODE_SHEVERY = 100;

    private final SheveryPrivilege.OnPermissionResultListener permListener =
            (requestCode, grantResult) -> {
                if (grantResult == PackageManager.PERMISSION_GRANTED) {
                    runPrivilegedTask();
                }
            };

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // Fast-pull binder immediately if not already attached
        SheveryPrivilege.connectFast(this);
        SheveryPrivilege.addPermissionResultListener(permListener);

        if (SheveryPrivilege.isGranted()) {
            runPrivilegedTask();
        } else {
            SheveryPrivilege.requestPermission(REQ_CODE_SHEVERY);
        }
    }

    private void runPrivilegedTask() {
        if (SheveryPrivilege.hasCapability(SheveryApiConstants.CAP_SHELL_EXEC)) {
            SheveryPrivilege.ExecResult res = SheveryPrivilege.execFast(new String[]{"id"});
            if (!res.timedOut && res.exitCode == 0) {
                String out = res.getOutputText();
            }
        }
    }

    @Override
    protected void onDestroy() {
        SheveryPrivilege.removePermissionResultListener(permListener);
        super.onDestroy();
    }
}

4. Wrap System Services (SheveryBinderWrapper)

IBinder rawBinder = SheveryPrivilege.getSystemService("package");
IPackageManager pm = IPackageManager.Stub.asInterface(rawBinder);

Github Workflows

1. Releases

Pushes to main and dev use conventional commits to determine the next version. main releases are stable and update manifest.gradle. Both publish to the maven branch and GitHub Packages, then create a GitHub release. The Maven branch retains older versions. The release script publishes the aidl, shared, api, and provider modules; add any new publishable modules to that list.

Publishing is not atomic across GitHub Packages, the Maven branch, and GitHub Releases. If publishing fails after a tag is created, inspect the failed run and the three destinations before repairing or retrying the affected publication; rerunning semantic-release alone will not republish an already tagged version.

2. Forks

Before enabling the workflow, create dev and maven in the repository, populate maven with the existing Maven repository, and import the existing vX.Y.Z release tags into the repository. The latest reachable tag must represent the last published release else version on fork will not match main repo.

Credits & Acknowledgements

Shevery-API builds upon the Android privileged IPC ecosystem and incorporates architectural and security improvements from the following projects:

  • kerneldroid / Nightzuku API (kerneldroid):
    • Zero-stub raw Parcel inspection (LegacyParcelCodec) with Android 13+ lazy-parcelable support.
    • One-shot bounded command execution (execFast / ExecResult) and fine-grained capability bitmasks (CAP_SHELL_EXEC, CAP_BINDER_PROXY, CAP_USER_SERVICE, CAP_SYSTEM_PROPS).
    • ActivityThread$AppBindData reflection initialization in UserService for reliable Application.onCreate() execution under app_process.
    • Cross-API IContentProviderUtils.callCompat with AttributionSource support and LinkageError fallback.
    • Thread-safe SystemServiceHelper binder liveness validation (pingBinder()) and RemoteProcessHolder unlinkTokenToDeath() cleanup.
    • Client-side RishTerminal stderr descriptor fix, setWindowSize reply parcel fix, and pipe descriptor cleanup.
  • d4rken-org / Porter API (d4rken-org):
    • transactRemote local server-binder privilege escalation check (targetBinder instanceof Binder).
    • Untrusted Bundle framework ClassLoader confinement (confineToFramework).
    • UserServiceRecord cached interfaceDescriptor lookup (preventing writeInterfaceToken(null) JNI aborts and wedged-binder round-trips on destroy()), broadcastBinderDied() notification on pre-attach failure, and multi-user (userId) service key isolation in UserServiceManager.
    • Native rish (porsh) PTY/process-group hardening: O_CLOEXEC / FD_CLOEXEC descriptor hygiene, F_DUPFD_CLOEXEC per-thread ptmx duplication, poll() output reader failure detection (watch_out), waitid + kill(-pid, SIGKILL) process-group termination, dual stdout/stderr drain synchronization (atomic_int pending), routable(tty) pipe routing, and uncollected exited host reaping in RishService / RishHost.
  • RikkaApps / Shizuku-API (RikkaW and contributors):
    • Original Shizuku AIDL interfaces, UserService concept, rish foundation, and compatibility layer.

License

MIT License

About

New API of Shevery that faster than Shizuku API

Resources

Stars

7 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages