{"id":13627463,"url":"https://github.com/EIPStackGroup/OpENer","last_synced_at":"2025-04-16T23:33:05.217Z","repository":{"id":10074600,"uuid":"12129915","full_name":"EIPStackGroup/OpENer","owner":"EIPStackGroup","description":"OpENer is an EtherNet/IP stack for I/O adapter devices. It supports multiple I/O and explicit connections and includes objects and services for making EtherNet/IP-compliant products as defined in the ODVA specification.","archived":false,"fork":false,"pushed_at":"2024-11-20T23:19:58.000Z","size":151146,"stargazers_count":688,"open_issues_count":51,"forks_count":261,"subscribers_count":84,"default_branch":"master","last_synced_at":"2024-11-20T23:28:29.476Z","etag":null,"topics":["c","cip","commonindustrialprotocol","ethernet","ethernetindustrialprotocol"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EIPStackGroup.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.txt","contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-08-15T08:22:41.000Z","updated_at":"2024-11-20T23:20:03.000Z","dependencies_parsed_at":"2023-02-17T05:45:56.859Z","dependency_job_id":"86c79c53-cb71-4b89-8141-3d894d67b704","html_url":"https://github.com/EIPStackGroup/OpENer","commit_stats":{"total_commits":1127,"total_committers":32,"mean_commits":35.21875,"dds":"0.45075421472937005","last_synced_commit":"aeab22031c753b54e2f0c773dfe986e965e36b57"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EIPStackGroup%2FOpENer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EIPStackGroup%2FOpENer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EIPStackGroup%2FOpENer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EIPStackGroup%2FOpENer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EIPStackGroup","download_url":"https://codeload.github.com/EIPStackGroup/OpENer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249288027,"owners_count":21244717,"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":["c","cip","commonindustrialprotocol","ethernet","ethernetindustrialprotocol"],"created_at":"2024-08-01T22:00:34.349Z","updated_at":"2025-04-16T23:33:04.776Z","avatar_url":"https://github.com/EIPStackGroup.png","language":"C","readme":"[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=EIPStackGroup_OpENer\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=EIPStackGroup_OpENer)\n[![Join the chat at https://gitter.im/EIPStackGroupOpENer/Lobby](https://badges.gitter.im/EIPStackGroupOpENer/Lobby.svg)](https://gitter.im/EIPStackGroupOpENer/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n\nOpENer Version 2.3.0\n====================\n\nWelcome to OpENer!\n------------------\n\nOpENer is an EtherNet/IP\u0026trade; stack for I/O adapter devices; supports multiple \nI/O and explicit connections; includes objects and services to make EtherNet/IP\u0026trade;-\ncompliant products defined in THE ETHERNET/IP SPECIFICATION and published by \nODVA (http://www.odva.org).\n\nParticipate!\n------------\nUsers and developers of OpENer can join the respective Google Groups in order to exchange experience, discuss the usage of OpENer, and to suggest new features and CIP objects, which would be useful for the community.\n\nDevelopers mailing list: https://groups.google.com/forum/#!forum/eip-stack-group-opener-developers\n\nUsers mailing list: https://groups.google.com/forum/#!forum/eip-stack-group-opener-users\n\nRequirements:\n-------------\nOpENer has been developed to be highly portable. The default version targets PCs\nwith a POSIX operating system and a BSD-socket network interface. To test this \nversion we recommend a Linux PC or Windows with Cygwin (http://www.cygwin.com) \ninstalled. You will need to have the following installed:\n\n* CMake\n* gcc\n* make\n* binutils\n* the development library of libcap (libcap-dev or equivalient)\n \nfor normal building. These should be installed on most Linux installations and\nare part of the development packages of Cygwin.\n\nIf you want to run the unit tests you will also have to download CppUTest via\nhttps://github.com/cpputest/cpputest\n\nFor configuring the project we recommend the use of a CMake GUI (e.g., the \ncmake-gui package on Linux, or the Installer for Windows available at [CMake](https://cmake.org/))\n\nCompile for Linux/POSIX:\n----------------\n1. Make sure all the needed tools are available (CMake, make, gcc, binutils)\n2. Change to the \u003cOpENer main folder\u003e/bin/posix\n3. For a standard configuration invoke ``setup_posix.sh``\n\t1. Invoke the ``make`` command\n\t2. Invoking OpENer:\n\n\t\t``./src/ports/POSIX/OpENer \u003cinterface_name\u003e``\n\n\t\te.g. ``./src/ports/POSIX/OpENer eth1``\n\nOpENer also now has a real-time capable POSIX startup via the OpENer_RT option, which requires that the used kernel has the full preemptive RT patches applied and activated.\nIf you want to use OpENer_RT, prior to step 2, execute ``sudo setcap cap_ipc_lock,cap_sys_nice+ep ./src/ports/POSIX/OpENer\n`` to grant OpENEr ``CAP_SYS_NICE``, and the ``CAP_IPC_LOCK`` capabilities, which are needed for the RT mode\n\nOpENer can also be built and installed as a library by setting the CMake flag `-DOPENER_INSTALL_AS_LIB`.  To build a shared library,\nthe global option `-DBUILD_SHARED_LIBS=ON` should also be set.  It has only been tested under Linux/POSIX platform.\n\n\nCompile for Windows XP/7/8 via Visual Studio:\n---------------------------------------------\n1. Invoke setup_windows.bat or configure via CMake\n2. Open Visual Studio solution OpENer.sln in bin/win32\n3. Compile OpENer by chosing ``Build All`` in Visual Studio\n4. For invoking OpENer type from the command line:\n\t1. Change to \u003cOpENer main folder\u003e\\bin\\win32\\src\\ports\\WIN32\\\n\t2. Depending if you chose the ``Debug`` or ``Release`` configuration in Visual Studio, your executable will either show up in the subfolder Debug or Release\n\t3. Invoke OpENer via\n\n\t\t``OpENer \u003cinterface_index\u003e``\n\n\t\te.g. ``OpENer 3``\n\nIn order to get the correct interface index enter the command ``route print`` in a command promt and search for the MAC address of your chosen network interface at the beginning of the output. The leftmost number is the corresponding interface index.\n\t\t\nCompile for Windows XP/7/8/10 via Cygwin:\n--------------------------------------\nThe POSIX setup file can be reused for Cygwin. Please note, that you cannot use RT mode and you will have to remove the code responsible for checking and getting the needed capabilities, as libcap is not available in Cygwin. The easier and more supported way to build OpENer for Windows is to either use MinGW or Visual Studio.\n\nCompile for MinGW on Windows XP/7/8/10\n-------------------------------\n1. Make sure 64 bit mingw is installed. (Test with gcc --version, should show x86_64-posix-seh-rev1)\n2. Make sure CMake is installed. (Test with cmake --version, should be version 3.xx)\n3. Change to \u003copener install dir\u003e/bin/mingw\n4. Run the command `setup_mingw.bat` in a dos command line. (Not a bash shell). If tracing is desired, \nuse the following (where the cmake parameter must be enclosed in quotes) or change the ./source/CMakeList.txt file.\n    ```\n    setup_mingw.bat \"-DOpENer_TRACES:BOOL=TRUE\"\n    ```\n5. Run the command \"make\" from the same directory (./bin/mingw)\n6. The opener.exe is now found in \u003copener install dir\u003e\\bin\\mingw\\src\\ports\\MINGW\n7. Start it like this: \"opener 192.168.250.22\", where the ip address is the local computer's address on the nettwork you want to use.\n\t\t\nDirectory structure:\n--------------------\n- bin ...  The resulting binaries and make files for different ports\n- doc ...  Doxygen generated documentation (has to be generated for the SVN version) and Coding rules\n- data ... EDS file for the default application\n- source\n\t- src ... the production source code\n\t\t- cip ... the CIP layer of the stack\n\t\t- cip_objects ... additional CIP objects\n\t\t- enet_encap ... the Ethernet encapsulation layer\n\t\t- ports ... the platform specific code\n\t\t- utils ... utility functions\n\t- tests ... the test source code\n\t\t- enet_encap ... tests for Ethernet encapsulation layer\n\t\t- utils ... tests for utility functions\n\nDocumentation:\n--------------\nThe documentation of the functions of OpENer is part of the source code. The source \npackages contain the generated documentation in the directory doc/api_doc. If you \nuse the GIT version you will need the program Doxygen for generating the HTML \ndocumentation. You can generate the documentation by invoking doxygen from the \ncommand line in the opener main directory.\n\n\nFuzzing\n--------------\n### Intro\nFuzzing is an automated testing method that directs varying input data to a program in \norder to monitor output. It is a way to test for overall reliability as well as identify \npotential security bugs.\n\nThe fuzzer we are using is AFL, a fuzzer that uses runtime guided techniques to create input for the tested program. From a high-level prespective AFL works as follows:\n- Forks the fuzzed process\n- Genereates a new test case based on a predefined input\n- Feeds the fuzzed process with the test case through STDIN\n- Monitors the execution and registers which paths are reachable\n\n![Alt text](fuzz/imgs/fuzz.png \"AFL Fuzzing\")\n\n### Compile\nTo start fuzzing this project with AFL you'll need to compile it with AFL.\nFirst make sure you have AFL installed:\n```\nsudo apt install build-essential\nwget http://lcamtuf.coredump.cx/afl/releases/afl-latest.tgz\ntar xzf afl-latest.tgz\ncd afl*\nmake \u0026\u0026 sudo make install\necho \"AFL is ready at: $(which afl-fuzz)\"\n\n```\n\nThen, compile OpENer with AFL:\n1. Change to the ``OpENer/bin/posix`` directory\n2. Compile OpENer with AFL ``./setup_posix_fuzz_afl.sh`` \n3. Run ``make``\n\n### Fuzz\nFinally, generate some test cases and start AFL:\n```\n# Generate inputs\nmkdir inputs\necho 630000000000000000000000000000000000000000000000 | xxd -r -p \u003e ./inputs/enip_req_list_identity\n# You can also use the inputs we prepared from OpENer/fuzz/inputs\n# Finally, let's fuzz!\nafl-fuzz -i inputs -o findings ./src/ports/POSIX/OpENer \u003cinterface_name\u003e\n```\n\n### Reproduce a crash\nUsually to reproduce a crash it's enough to retransmit the testcase using ``cat testcase | nc IP_ADDR 44818``\nHowever, since CIP runs over the EtherNet/IP layer, it must first register a valid session. Therefore, we need to use a dedicated script:\n`python fuzz/scripts/send_testcase.py IP testcase_path`\n\nRunning an OpENer \"swarm\":\n--------------------------\n\n1. Create a macvlan network for this purpose and tie it to the desired eth port.\nSpecify the IP range and use aux address to exclude the addresses used by other devices in the subnet such as the IP of the EIP scanner PC, network bridge, etc.:\ndocker network create -d macvlan --subnet=192.168.135.253/24 --ip-range=192.168.135.100/24 --aux-address=\"PC1=192.168.135.250\" --aux-address=\"VM=192.168.135.252\" --aux-address=\"BR=192.168.135.253\" -o parent=eth2 mac_vlan_network\n\nCheck the network you created with: docker network inspect mac_vlan_network\n\nThe network will assign IP's to the docker containers and an external scanner will be able to communicate with them. To access the containers from inside the docker host, you will have to create a bridge.\n\n2. Create a Dockerfile.\nThis uses Ubuntu as the base image. It will copy OpENer to the image root and install the required packages. Lastly run OpENer on eth0 of the image:\n#Filename: Dockerfile\nFROM ubuntu:20.04\nADD ./bin/posix/src/ports/POSIX/OpENer /\nRUN apt-get update \u0026\u0026 apt-get install -y --no-install-recommends libcap-dev nmap\nENTRYPOINT [\"./OpENer\", \"eth0\"]\n\n3. Create a docker-compose.yml that will let you connect the macvlan network to the containers and easily build them and tear them down:\nversion: \"3.3\"\nservices:\ndockerimagename:\nnetwork_mode: mac_vlan_network\nimage: dockeruser/dockerimagename\n\nNote that to login to a running container, you have to expose a port in the dockerfile and dockercompose files and set up a network bridge.\n\nDocker commands to start and stop multiple instances of the OpENer containers:\nStart up 128 docker image instances: docker-compose up --scale dockerimagename=128 -d\nShut down all the instances: docker-compose down\n\nPorting OpENer:\n---------------\nFor porting OpENer to new platforms please see the porting section in the \nDoxygen documentation.\n\nContributing to OpENer:\n-----------------------\nThe easiest way is to fork the repository, then create a feature/bugfix branch.\nAfter finishing your feature/bugfix create a pull request and explain your changes.\nAlso, please update and/or add doxygen comments to the provided code sections.\nPlease stick to the coding conventions, as defined in source/doc/coding_rules\nThe easiest way to conform to the indenting convertion is to set uncrustify as git filter in the OpENer repository, which can be done with the following to commands:\n\n```\ngit config filter.uncrustify.clean \"/path/to/uncrustify/uncrustify -c uncrustify.cfg --mtime --no-backup\"\n\ngit config filter.uncrustify.smudge \"cat\"\n```\n\n\n","funding_links":[],"categories":["Ethernet/IP"],"sub_categories":["Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEIPStackGroup%2FOpENer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEIPStackGroup%2FOpENer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEIPStackGroup%2FOpENer/lists"}