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.
| 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 |
- Fast-Pull Binder Acquisition (
SheveryPrivilege.connectFast(context)): Unlike legacy Shizuku clients that passively wait forIActivityManagerprocess/UID observers and retry backoffs,SheveryProviderandSheveryPrivilege.connectFast(context)pull the active server binder directly fromcontent://com.hamondev.shevery.shevery(METHOD_REQUEST_BINDER) in a single IPC call on startup. - Zero-Stub Raw Parcel Codec (
LegacyParcelCodec): Inspects rawBUNDLE_MAGIC_NATIVE(0x4C444E42) parcel bytes (including Android 13+ lazy parcelables) beforeBaseBundle.unparcel()is triggered, preventingClassNotFoundException/BadParcelableExceptionacross 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 KBmax per stream) and configurable timeout (30sdefault) without spawning 3 separateParcelFileDescriptorpipe 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
transactRemotecalls targeting localBinderinstances of the server process itself so normal granted clients cannot invoke manager-only endpoints afterBinder.clearCallingIdentity(). - Untrusted Bundle Confinement: Confines incoming server
Bundlearguments to the frameworkClassLoader(Bundle.class.getClassLoader()) prior to unparceling. - Multi-User
UserServiceIsolation & JNI Abort Protection: KeysUserServiceRecordentries byuserId:packageName:tagOrClass, cachesinterfaceDescriptoron binder attach to avoid synchronous round-trips orwriteInterfaceToken(null)JNI aborts duringdestroy(), and initializesActivityThread$AppBindDataprior toLoadedApk.makeApplication(). - Hardened
rishPTY Lifecycle: Fixesstderrpipe descriptor routing, closes PTY master descriptors (ptmx) on process exit, detaches native transfer pthreads (pthread_detach), monitors output pipe reader loss viapoll(), terminates child process groups cleanly viawaitid+kill(-pid, SIGKILL), and reaps uncollected exited hosts.
- Direct Process Execution: Executes command arrays directly via
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"
}<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>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();
}
}IBinder rawBinder = SheveryPrivilege.getSystemService("package");
IPackageManager pm = IPackageManager.Stub.asInterface(rawBinder);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.
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.
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
Parcelinspection (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$AppBindDatareflection initialization inUserServicefor reliableApplication.onCreate()execution underapp_process.- Cross-API
IContentProviderUtils.callCompatwithAttributionSourcesupport andLinkageErrorfallback. - Thread-safe
SystemServiceHelperbinder liveness validation (pingBinder()) andRemoteProcessHolderunlinkTokenToDeath()cleanup. - Client-side
RishTerminalstderrdescriptor fix,setWindowSizereply parcel fix, and pipe descriptor cleanup.
- Zero-stub raw
- d4rken-org / Porter API (
d4rken-org):transactRemotelocal server-binder privilege escalation check (targetBinder instanceof Binder).- Untrusted
BundleframeworkClassLoaderconfinement (confineToFramework). UserServiceRecordcachedinterfaceDescriptorlookup (preventingwriteInterfaceToken(null)JNI aborts and wedged-binder round-trips ondestroy()),broadcastBinderDied()notification on pre-attach failure, and multi-user (userId) service key isolation inUserServiceManager.- Native
rish(porsh) PTY/process-group hardening:O_CLOEXEC/FD_CLOEXECdescriptor hygiene,F_DUPFD_CLOEXECper-threadptmxduplication,poll()output reader failure detection (watch_out),waitid+kill(-pid, SIGKILL)process-group termination, dualstdout/stderrdrain synchronization (atomic_int pending),routable(tty)pipe routing, and uncollected exited host reaping inRishService/RishHost.
- RikkaApps / Shizuku-API (
RikkaWand contributors):- Original Shizuku AIDL interfaces,
UserServiceconcept,rishfoundation, and compatibility layer.
- Original Shizuku AIDL interfaces,
MIT License