{"id":16558422,"url":"https://github.com/megatronking/netbare-android","last_synced_at":"2025-05-16T04:06:25.336Z","repository":{"id":41258673,"uuid":"162817691","full_name":"MegatronKing/NetBare-Android","owner":"MegatronKing","description":"Net packets capture \u0026 injection library designed for Android","archived":false,"fork":false,"pushed_at":"2022-08-21T05:14:43.000Z","size":785,"stargazers_count":1311,"open_issues_count":56,"forks_count":351,"subscribers_count":50,"default_branch":"master","last_synced_at":"2024-10-11T20:11:08.473Z","etag":null,"topics":["capture","http","http2","injection","ssl","tcp-ip"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MegatronKing.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-22T14:26:46.000Z","updated_at":"2024-10-11T10:02:01.000Z","dependencies_parsed_at":"2022-07-13T13:50:30.786Z","dependency_job_id":null,"html_url":"https://github.com/MegatronKing/NetBare-Android","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MegatronKing%2FNetBare-Android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MegatronKing%2FNetBare-Android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MegatronKing%2FNetBare-Android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MegatronKing%2FNetBare-Android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MegatronKing","download_url":"https://codeload.github.com/MegatronKing/NetBare-Android/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254464895,"owners_count":22075570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["capture","http","http2","injection","ssl","tcp-ip"],"created_at":"2024-10-11T20:10:41.494Z","updated_at":"2025-05-16T04:06:20.327Z","avatar_url":"https://github.com/MegatronKing.png","language":"Java","readme":"# NetBare\nNetBare是一款网络包拦截和注入框架，可以实现抓包、屏蔽包、改包等各种强大功能。NetBare核心是基于VPN技术，将网络包转发到本地代理服务器，再通过虚拟网关（VirtualGateway）进行拦截分发。在设计上，虚拟网关层是完全对外开放的，开发者可以自由定义虚拟网关，也可以使用NetBare内部已实现的虚拟网关进行网络包的处理。\n\n## NetBare初始化\n1. 在Application中绑定\n```kotlin\nNetBare.get().attachApplication(application, BuildConfig.DEBUG)\n```\n\n2. 创建自签证书（SSL需要）\n```kotlin\nval jks = JKS(context, alias, password, commonName, organization,\n        organizationalUnitName, certOrganization, certOrganizationalUnitName)\n```\n\n3. 安装自签证书（SSL需要）\n```kotlin\n// 判断证书是否安装\nJKS.isInstalled(context, alias)\n// 安装证书\nJKS.install(context, name, alias)\n```\n\n4. 创建NetBare服务。由于NetBare具有危险性，所以在设计上会强制要求在通知栏提示用户服务正在运行，同时要在Manifest中配置Service。\n```kotlin\n// 继承NetBareService创建自己应用的Service\nclass AppService : NetBareService() {\n        override fun notificationId(): Int {\n            // 通知栏ID\n        }\n        override fun createNotification(): Notification {\n            // 创建一个Notification\n        }\n}\n```\n```xml\n\u003cservice android:name=\".AppService\"\n            android:permission=\"android.permission.BIND_VPN_SERVICE\"\u003e\n            \u003cintent-filter\u003e\n                \u003caction android:name=\"android.net.VpnService\" /\u003e\n                \u003caction android:name=\"com.github.megatronking.netbare.action.Start\"/\u003e\n                \u003caction android:name=\"com.github.megatronking.netbare.action.Stop\"/\u003e\n            \u003c/intent-filter\u003e\n\u003c/service\u003e\n```\n\n5. NetBare服务的启动和停止\n```kotlin\n// 通过NetBareConfig自由配置NetBare服务并启动\nNetBare.get().start(NetBareConfig)\n// 停止NetBare服务\nNetBare.get().stop()\n```\n\n## NetBareConfig配置\n\nNetBareConfig需要使用NetBareConfig.Builder进行构造，解释下以下几个重要的配置方法。\n- setMtu 最大传输单元，必要，建议大于2048。\n- setAddress 本地代理服务器IP地址，必要，建议用A类IP地址，防止冲突。\n- addRoute 设置经过VPN的目标IP包，必要，建议使用0.0.0.0，所有IP全部经过VPN。\n- dumpUid 是否dump网络包所属的uid，可选，耗电方法，建议false\n- setVirtualGatewayFactory 配置虚拟网关，可选。\n\nNetBare框架提供了默认的NetBareConfig来快速集成：\n```kotlin\n// 创建默认的NetBareConfig，作用于所有IP协议\nval config = NetBareConfig.defaultConfig()\n// 为Http协议创建默认的NetBareConfig\nval config = NetBareConfig.defaultHttpConfig(jks, interceptors)\n```\n\n## NetBare虚拟网关\n\n虚拟网关是对网络包进行拦截、解析、注入的核心，可以加载开发者自定义的拦截器，通过NetBareConfig.Builder来配置。NetBare框架提供了两个默认的虚拟网关对象。\n\n#### DefaultVirtualGateway\n默认虚拟网关，可以拦截到所有协议的网络包。默认虚拟网关无法直接构造，需要通过DefaultVirtualGatewayFactory来进行构造。开发者可以使用NetBareConfig.setVirtualGatewayFactory配置默认虚拟网关工厂。\n```kotlin\n// 配置自定义拦截器\nval interceptors = listOf(...)\n//  创建默认虚拟网关工厂\nval defaultGatewayFactory = DefaultVirtualGatewayFactory(interceptors)\n// 通过NetBareConfig.Builder来配置defaultGatewayFactory\n...\n```\n虚拟网关拦截器，继承Interceptor。Interceptor使用工厂模式，由InterceptorFactory来构造。\n```kotlin\nclass TestIntercepter : Interceptor {\n\n    @Throws(IOException::class)\n    override fun intercept(chain: RequestChain, buffer: ByteBuffer) {\n        // 对请求包进行自定义处理\n        ...\n        // 将请求发射出去，交给下个拦截器或者发给服务器\n        chain.process(buffer)\n    }\n\n    @Throws(IOException::class)\n    override fun intercept(chain: ResponseChain, buffer: ByteBuffer) {\n        // 对响应包进行处理\n        ...\n        // 将响应发射出去，交给下个拦截器或者发给客户端\n        chain.process(buffer)\n    }\n\n    override fun onRequestFinished(request: Request) {\n        // 请求包已全部发送完成\n    }\n\n    override fun onResponseFinished(response: Response) {\n        // 响应包已全部发送完成\n    }\n}\n```\n\n\n#### HttpVirtualGateway\nHttp协议虚拟网关，可以拦截到所有Http协议的网络包。Http协议虚拟网关也无法直接构造，需要通过HttpVirtualGatewayFactory来进行构造。创建HttpVirtualGatewayFactory实例需要前面的JKS以及拦截器HttpInterceptor。\n```kotlin\n// 配置自定义HttpInterceptor\nval interceptors = listOf(...)\n//  创建Http虚拟网关工厂\nval httpGatewayFactory = HttpVirtualGatewayFactory(jks, interceptors)\n// 通过NetBareConfig.Builder来配置httpGatewayFactory\n...\n```\nHttp虚拟网关拦截器，继承HttpInterceptor。同样的HttpInterceptor也使用工厂模式，由HttpInterceptorFactory来构造。\n\n```kotlin\nclass TestHttpIntercepter : HttpInterceptor() {\n\n    override fun intercept(chain: HttpRequestChain, buffer: ByteBuffer) {\n        // 对Http请求包进行自定义处理\n        ...\n        // 将Http请求发射出去，交给下个拦截器或者发给服务器\n        chain.process(buffer)\n    }\n\n    override fun intercept(chain: HttpResponseChain, buffer: ByteBuffer) {\n        // 对Http响应包进行自定义处理\n        ...\n        // 将Http响应发射出去，交给下个拦截器或者发给客户端\n        chain.process(buffer)\n    }\n\n    override fun onRequestFinished(request: HttpRequest) {\n        // Http请求包已全部发送完成\n    }\n\n    override fun onResponseFinished(response: HttpResponse) {\n        // Http响应包已全部发送完成\n    }\n\n}\n```\n此外，NetBare框架内置了HttpIndexInterceptor等特殊拦截器方便开发者使用。\n\n## 注入器Injector\nNetBare提供了一套通用的injector框架来方便开发者注入请求和响应。Injector框架是基于虚拟网关的拦截器来运行的。目前只开发了针对Http协议的注入器，其它协议可以后续再扩展。\n\nHttp协议的注入是基于HttpInjectInterceptor拦截器来实现的，在配置HttpVirtualGatewayFactory的时候，需要配置此拦截器，每一个注入器对应一个拦截器实例。而所有注入器都必须实现HttpInjector接口。\n```kotlin\nclass TestHttpInjector : HttpInjector {\n\n    override fun sniffRequest(request: HttpRequest): Boolean {\n        // 对request进行判定，是否需要注入。true表示需要注入。\n        return false\n    }\n\n    override fun sniffResponse(response: HttpResponse): Boolean {\n        // 对response进行判定，是否需要注入。true表示需要注入。\n        return false\n    }\n\n    @Throws(IOException::class)\n    override fun onRequestInject(header: HttpRequestHeaderPart,\n                                 callback: InjectorCallback) {\n        // 当sniffRequest返回true时，会走到此方法。\n        // 对请求头部进行注入，包括method、url、headers都可以修改\n        ...\n        // 将注入完成后将新的数据发射出去\n        callback.onFinished(header)\n    }\n\n    @Throws(IOException::class)\n    override fun onResponseInject(header: HttpResponseHeaderPart,\n                                  callback: InjectorCallback) {\n        // 当sniffResponse返回true时，会走到此方法。\n        // 对响应头部进行注入，包括code、message、headers都可以修改\n        ...\n        // 将注入完成后将新的数据发射出去\n        callback.onFinished(header)\n    }\n\n    @Throws(IOException::class)\n    override fun onRequestInject(request: HttpRequest, body: HttpBody,\n                                 callback: InjectorCallback) {\n        // 当sniffRequest返回true时，会走到此方法。\n        // 对请求体进行注入，如果请求体数据较大，会多次走到此方法。\n        ...\n        // 将注入完成后将新的数据发射出去\n        callback.onFinished(body)\n    }\n\n    @Throws(IOException::class)\n    override fun onResponseInject(response: HttpResponse, body: HttpBody,\n                                  callback: InjectorCallback) {\n        // 当sniffResponse返回true时，会走到此方法。\n        // 对响应体进行注入，如果请求体数据较大，会多次走到此方法。\n        ...\n        // 将注入完成后将新的数据发射出去\n        callback.onFinished(body)\n    }\n\n    override fun onRequestFinished(request: HttpRequest) {\n        // Http请求包已全部发送完成\n    }\n\n    override fun onResponseFinished(response: HttpResponse) {\n        // Http响应包已全部发送完成\n    }\n```\n将注入器绑定到拦截器，并装载到虚拟网关中：\n```kotlin\n// 配置自定义HttpInjectInterceptor\nval interceptor1 = HttpInjectInterceptor.createFactory(injector1)\nval interceptor2 = HttpInjectInterceptor.createFactory(injector2)\n...\nval interceptors = listOf(interceptor1, interceptor2 ...)\n//  创建Http虚拟网关工厂\nval httpGatewayFactory = HttpVirtualGatewayFactory(jks, interceptors)\n// 通过NetBareConfig.Builder来配置httpGatewayFactory\n...\n```\n\n## NetBare范例\nNetBare的接入步骤就有些繁琐，所以提供了一个简单的Sample工程供大家参考。sample中包含三个比较有趣的东西：\n- 拦截器1：打印所有Http请求的URL。\n- 注入器1：将百度首页的logo图片修改成自定义的图片。\n- 注入器2：将发朋友圈的定位地点修改到珠峰。\n\n![](https://github.com/MegatronKing/NetBare/blob/master/assets/sample1.png)\n![](https://github.com/MegatronKing/NetBare/blob/master/assets/sample2.png)\n\n## 结语\nNetBare框架尚未完全成熟，仍然有很多工作要做，包括ICMP、IGMP等IP协议的转发等等，后续会继续完善。\n\n基于NetBare实现的一款抓包+注入工具，欢迎大家下载体验：https://play.google.com/store/apps/details?id=com.guoshi.httpcanary\n\n**声明：DON'T BE EVIL！NetBare只可用于学习和调试，禁止用于网络恶意攻击和钓鱼等非法途径**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegatronking%2Fnetbare-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmegatronking%2Fnetbare-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegatronking%2Fnetbare-android/lists"}